@picteus/extension-sdk 0.17.0 → 0.19.0

package/dist/generated/viewKit.d.ts

@@ -15,75 +15,156 @@ export declare abstract class ViewKitNode<T = unknown> {
 }
 /** Typographic stroke weight styling. */
 export declare enum TextWeight {
+    /** Thin / light text weight */
     thin = "thin",
+    /** Standard text weight */
     normal = "normal",
+    /** Heavy / bold text weight */
     heavy = "heavy"
 }
 /** Visual text color intensity and contrast. */
 export declare enum TextIntensity {
+    /** Low visual contrast / subdued text color */
     low = "low",
+    /** Standard text color */
     medium = "medium",
+    /** High visual contrast / intense text color */
     high = "high"
 }
 /** Geometric shape representation for visual containers and indicators. */
 export declare enum Shape {
+    /** Circular container shape */
     circle = "circle",
+    /** Square container shape */
     square = "square"
 }
 /** Relative sizing scale for visual elements and indicators. */
 export declare enum Size {
+    /** Compact small size */
     small = "small",
+    /** Standard medium size */
     medium = "medium",
+    /** Prominent large size */
     large = "large"
 }
-/** Representation style for short string values. */
-export declare enum StringShortRepresentation {
+/** Visual presentation style for string values. */
+export declare enum StringRepresentation {
+    /** Standard inline text rendering */
     plain = "plain",
-    chip = "chip"
+    /** Visual chip / tag pill representation */
+    chip = "chip",
+    /** Multiline text with preserved whitespace and line breaks */
+    multiline = "multiline"
+}
+/** Visual separator rendered between sequential elements or items. */
+export declare enum Separator {
+    /** Vertical dividing bar */
+    bar = "bar",
+    /** Comma separator */
+    comma = "comma",
+    /** Bullet dot separator */
+    dot = "dot",
+    /** Forward slash separator */
+    slash = "slash",
+    /** Dash separator */
+    dash = "dash",
+    /** Space separator */
+    space = "space"
 }
 /** Supported syntax highlighting languages for formatted code blocks. */
 export declare enum CodeLanguage {
+    /** XML markup syntax */
     xml = "xml",
+    /** JSON format syntax */
     json = "json",
+    /** YAML format syntax */
     yaml = "yaml"
 }
+/** Visual presentation style for boolean values. */
+export declare enum BooleanRepresentation {
+    /** Standard inline text rendering (e.g. "true" / "false" or custom labels) */
+    plain = "plain",
+    /** Visual badge pill representation */
+    badge = "badge"
+}
 /** Visual color tone variants for badge pill representations. */
 export declare enum BadgeVariant {
+    /** Neutral gray tone */
     neutral = "neutral",
+    /** Success green tone */
     success = "success",
+    /** Warning yellow/orange tone */
     warning = "warning",
+    /** Danger red tone */
     danger = "danger"
 }
 /** Presentation format styles for timestamp elements. */
 export declare enum TimestampFormat {
+    /** Complete date and time display */
     datetime = "datetime",
+    /** Date-only display */
     date = "date",
+    /** Time-only display */
     time = "time",
+    /** Relative time expression (e.g. "5 minutes ago") */
     relative = "relative"
 }
 /** Visual style variants for interactive button actions. */
 export declare enum ButtonVariant {
+    /** Primary emphasis button style for default/recommended actions */
     primary = "primary",
+    /** Secondary standard button style */
     secondary = "secondary",
+    /** Subtle low-contrast button style */
     subtle = "subtle",
+    /** Destructive / dangerous action button style */
     danger = "danger"
 }
-/** Text horizontal alignment options for table columns. */
+/**
+ * Text horizontal alignment options for table columns.
+ *
+ * @remarks
+ * Horizontal alignment applied within cells of a TableColumn. The alignment is a presentation choice and does not affect the stored cell values.
+ */
 export declare enum TableColumnAlign {
+    /** Left-aligned text */
     left = "left",
+    /** Center-aligned text */
     center = "center",
+    /** Right-aligned text */
     right = "right"
 }
-/** Visual styling variants for hairline dividers. */
+/**
+ * Width mode for table columns.
+ *
+ * @remarks
+ * Controls how an optional TableColumn width is interpreted by the table renderer.
+ */
+export declare enum TableColumnWidthMode {
+    /** Fixed width constraint */
+    fixed = "fixed",
+    /** Maximum width upper bound constraint */
+    maximum = "maximum"
+}
+/**
+ * Visual styling variants for hairline dividers.
+ *
+ * @remarks
+ * Selects the visual stroke treatment used by DividerElement.
+ */
 export declare enum DividerStyle {
+    /** Subtle thin hairline border */
     hairline = "hairline",
+    /** Solid standard divider line */
     solid = "solid",
+    /** Dashed separator line */
     dashed = "dashed"
 }
 /**
- * Polymorphic root base model for all visual UI elements in Picteus feature views.
- * Uses the @discriminator("type") decorator so all child models inheriting from UiElement
- * are automatically recognized by schema emitters and SDK code generators.
+ * Polymorphic root model for visual UI elements.
+ *
+ * @remarks
+ * Every concrete visual element carries a type discriminator whose literal value selects its model and renderer. The @discriminator("type") metadata lets schema emitters and SDK generators represent derived models as a polymorphic hierarchy. Consumers should dispatch on the discriminator and preserve unknown elements when round-tripping data where possible.
  */
 export interface UiElementBase {
     /** The polymorphic discriminator type tag. */
@@ -93,11 +174,21 @@ export interface UiElementBase {
 export declare abstract class BaseUiElement<T = UiElement> extends ViewKitNode<T> implements UiElementBase {
     abstract readonly type: string;
 }
-/** Polymorphic base model for interactive actions. */
+/**
+ * Polymorphic base model for interactive actions.
+ *
+ * @remarks
+ * Shared action contract for user-invokable card controls. Concrete action models provide their own discriminator and action-specific destination or command fields.
+ */
 export interface UiActionBase {
     /** The polymorphic discriminator type tag. */
     readonly type: string;
-    /** Display label for the action */
+    /**
+     * Display label for the action
+     *
+     * @remarks
+     * User-facing label shown on the control. Keep it short and action-oriented.
+     */
     readonly label: string;
 }
 /** Abstract base class for all `UiAction` models. */
@@ -105,81 +196,164 @@ export declare abstract class BaseUiAction<T = UiAction> extends ViewKitNode<T>
     abstract readonly type: string;
     abstract readonly label: string;
 }
-/** Truncation configuration for long textual content with optional expand affordance. */
+/**
+ * Truncation configuration for long textual content with optional expand affordance.
+ *
+ * @remarks
+ * Controls how a renderer abbreviates long text. The character limit is a presentation threshold rather than a validation limit; showMore lets the user reveal the remaining text.
+ */
 export interface TruncateOptions {
-    /** Maximum number of characters to display before truncating */
+    /**
+     * Maximum number of characters to display before truncating
+     *
+     * @remarks
+     * Threshold after which the renderer can shorten the displayed text. This does not constrain the stored string or remove its undisplayed content.
+     */
     readonly characterLimit: number;
     /**
      * Whether to render a "Show more" / "Show less" toggle affordance
      *
+     * @remarks
+     * When true, permits an expand/collapse control for text beyond the truncation threshold. Defaults to true.
+     *
      * @defaultValue true
      */
     readonly showMore?: boolean;
 }
-/** Base modifier traits for elements that support copy affordance. */
+/**
+ * Base modifier traits for elements that support copy affordance.
+ *
+ * @remarks
+ * Common optional presentation traits shared by primitive values and content renderers. Modifiers affect how content is displayed or copied; they do not transform the source value.
+ */
 export interface BaseModifiers {
-    /** Adds an interactive copy button/action next to the rendered value */
+    /**
+     * Adds an interactive copy button/action next to the rendered value
+     *
+     * @remarks
+     * When true, exposes a copy affordance for the associated value where supported by the renderer.
+     */
     readonly copyable?: boolean;
 }
-/** Common modifier traits that can be attached to primitive elements. */
+/**
+ * Common modifier traits that can be attached to primitive elements.
+ *
+ * @remarks
+ * Extends BaseModifiers with text styling controls. Defaults provide normal weight, medium intensity, and proportional text unless a feature explicitly overrides them.
+ */
 export interface PrimitiveModifiers extends BaseModifiers {
-    /** Configures character truncation threshold with show-more affordance */
+    /**
+     * Configures character truncation threshold with show-more affordance
+     *
+     * @remarks
+     * Optional text abbreviation behavior. The source text remains unchanged, and the renderer may offer expansion according to showMore.
+     */
     readonly truncate?: TruncateOptions;
     /**
      * Typographic text weight
      *
+     * @remarks
+     * Relative font weight for textual rendering; defaults to normal.
+     *
      * @defaultValue TextWeight.normal
      */
     readonly weight?: TextWeight;
     /**
      * Visual text color intensity
      *
+     * @remarks
+     * Relative contrast treatment for the text; defaults to medium.
+     *
      * @defaultValue TextIntensity.medium
      */
     readonly intensity?: TextIntensity;
     /**
      * Whether to use monospace font rendering (for hashes, IDs, codes)
      *
+     * @remarks
+     * When true, requests a fixed-width font suitable for identifiers and code-like values. Defaults to false.
+     *
      * @defaultValue false
      */
     readonly monospace?: boolean;
 }
 /**
- * Short string primitive element.
- * Supports plain text or compact chip pill presentation.
+ * Text value primitive with selectable inline, chip, or multiline presentation.
+ *
+ * @remarks
+ * Use this primitive for one textual value when a structured label/value row is unnecessary. Choose multiline for content whose line breaks should remain visible; modifiers apply presentation traits without changing the underlying value.
  */
-export interface StringShortElement extends UiElementBase {
+export interface StringElement extends UiElementBase {
     /**
      * Discriminator type
      *
-     * @defaultValue "string-short"
+     * @defaultValue "string"
+     */
+    readonly type: "string";
+    /**
+     * Text value
+     *
+     * @remarks
+     * Text to render. Supply plain text; this field is not a Markdown or HTML document.
      */
-    readonly type: "string-short";
-    /** Text value */
     readonly value: string;
     /**
      * Display representation mode
      *
-     * @defaultValue StringShortRepresentation.plain
+     * @remarks
+     * Selects inline, chip, or multiline rendering. The default is plain, so callers can omit this for ordinary text.
+     *
+     * @defaultValue StringRepresentation.plain
      */
-    readonly representation?: StringShortRepresentation;
+    readonly representation?: StringRepresentation;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     readonly modifiers?: PrimitiveModifiers;
 }
-/** Multiline text block primitive element for descriptions, comments, or prose. */
-export interface StringLongElement extends UiElementBase {
+/**
+ * Collection of textual values rendered as an inline sequence or chips.
+ *
+ * @remarks
+ * Use this primitive when several related strings should be rendered as one compact sequence. The client preserves the array order and inserts the selected separator between values.
+ */
+export interface StringsElement extends UiElementBase {
     /**
      * Discriminator type
      *
-     * @defaultValue "string-long"
+     * @defaultValue "strings"
      */
-    readonly type: "string-long";
-    /** Text value */
-    readonly value: string;
+    readonly type: "strings";
+    /**
+     * Array of string values
+     *
+     * @remarks
+     * Values to render in order. Each array entry remains a distinct item for chip presentation and is not parsed as a delimited string.
+     */
+    readonly values: string[];
+    /**
+     * Display representation mode (plain text or visual chips)
+     *
+     * @remarks
+     * Selects whether values appear as ordinary inline text or as separate visual chips. The default uses the plain representation.
+     *
+     * @defaultValue StringRepresentation.plain
+     */
+    readonly representation?: StringRepresentation;
+    /**
+     * Optional visual separator rendered between sequential values
+     *
+     * @remarks
+     * Separator inserted between adjacent values in plain representation. It does not become part of any value.
+     */
+    readonly separator?: Separator;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     readonly modifiers?: PrimitiveModifiers;
 }
-/** Monospace code block or formatted code snippet representation. */
+/**
+ * Monospace code block or formatted code snippet representation.
+ *
+ * @remarks
+ * Use for source-like or preformatted textual content that should be rendered in a code-oriented style. The language is a presentation hint; the content is not parsed or validated as code by this contract.
+ */
 export interface StringCodeElement extends UiElementBase {
     /**
      * Discriminator type
@@ -187,14 +361,29 @@ export interface StringCodeElement extends UiElementBase {
      * @defaultValue "string-code"
      */
     readonly type: "string-code";
-    /** Text value */
+    /**
+     * Text value
+     *
+     * @remarks
+     * Code or text snippet to display. Include any desired line breaks in this string.
+     */
     readonly value: string;
-    /** Optional syntax highlighting language identifier */
+    /**
+     * Optional syntax highlighting language identifier
+     *
+     * @remarks
+     * Optional syntax hint for the renderer. Supported values describe highlighting modes and do not validate the snippet's syntax.
+     */
     readonly language?: CodeLanguage;
     /** Optional visual modifiers (copyable) */
     readonly modifiers?: BaseModifiers;
 }
-/** XML markup code block element. */
+/**
+ * XML markup code block element.
+ *
+ * @remarks
+ * Specialized code-oriented element for XML content. It uses the custom XML renderer rather than requiring consumers to construct a generic code block.
+ */
 export interface XmlElement extends UiElementBase {
     /**
      * Discriminator type
@@ -202,12 +391,22 @@ export interface XmlElement extends UiElementBase {
      * @defaultValue "xml"
      */
     readonly type: "xml";
-    /** XML content value */
+    /**
+     * XML content value
+     *
+     * @remarks
+     * XML markup to render. The contract carries the source text; it does not guarantee that the document is well-formed.
+     */
     readonly value: string;
     /** Optional visual modifiers (copyable) */
     readonly modifiers?: BaseModifiers;
 }
-/** JSON data or structure representation element. */
+/**
+ * JSON data or structure representation element.
+ *
+ * @remarks
+ * Specialized representation for JSON text. Supply serialized JSON when consumers should display a JSON document; this field is a string and is not structurally validated here.
+ */
 export interface JsonElement extends UiElementBase {
     /**
      * Discriminator type
@@ -215,12 +414,22 @@ export interface JsonElement extends UiElementBase {
      * @defaultValue "json"
      */
     readonly type: "json";
-    /** JSON content value */
+    /**
+     * JSON content value
+     *
+     * @remarks
+     * Serialized JSON text to render. No parsing or schema validation is implied by this element.
+     */
     readonly value: string;
     /** Optional visual modifiers (copyable) */
     readonly modifiers?: BaseModifiers;
 }
-/** Hyperlink representation for external or internal URL navigation. */
+/**
+ * Hyperlink representation for external or internal URL navigation.
+ *
+ * @remarks
+ * Use this element when displayed text should also behave as a link. Unlike StringElement, the value is a navigation destination and may be paired with a separate human-readable label.
+ */
 export interface StringUrlElement extends UiElementBase {
     /**
      * Discriminator type
@@ -228,14 +437,24 @@ export interface StringUrlElement extends UiElementBase {
      * @defaultValue "string-url"
      */
     readonly type: "string-url";
-    /** Target URL or navigation destination */
+    /**
+     * Target URL or navigation destination
+     *
+     * @remarks
+     * Destination associated with the link. Supply a URL or client-recognized navigation target supported by the renderer.
+     */
     readonly value: string;
     /** Optional custom anchor text label */
     readonly label?: string;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     readonly modifiers?: PrimitiveModifiers;
 }
-/** Monospace semantic identifier representation. */
+/**
+ * Monospace semantic identifier representation.
+ *
+ * @remarks
+ * Use for identifiers, hashes, and other machine-oriented strings that benefit from monospace styling. The value remains text and is not resolved as a Picteus entity.
+ */
 export interface IdentifierElement extends UiElementBase {
     /**
      * Discriminator type
@@ -243,12 +462,22 @@ export interface IdentifierElement extends UiElementBase {
      * @defaultValue "identifier"
      */
     readonly type: "identifier";
-    /** Identifier string value */
+    /**
+     * Identifier string value
+     *
+     * @remarks
+     * Identifier text to display, such as an opaque ID or hash. Avoid embedding presentation markup in the value.
+     */
     readonly value: string;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     readonly modifiers?: PrimitiveModifiers;
 }
-/** Aspect ratio representation (e.g. "16:9", "4:3", "1:1"). */
+/**
+ * Aspect ratio representation (e.g. "16:9", "4:3", "1:1").
+ *
+ * @remarks
+ * Displays a numeric aspect ratio as a ratio expression. Provide a positive value meaningful to the surrounding content; this type does not encode the source image dimensions.
+ */
 export interface RatioElement extends UiElementBase {
     /**
      * Discriminator type
@@ -256,12 +485,52 @@ export interface RatioElement extends UiElementBase {
      * @defaultValue "ratio"
      */
     readonly type: "ratio";
-    /** Aspect ratio numerical expression */
+    /**
+     * Aspect ratio numerical expression
+     *
+     * @remarks
+     * Numeric ratio value used by the renderer to produce an aspect-ratio display.
+     */
     readonly value: number;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     readonly modifiers?: PrimitiveModifiers;
 }
-/** Single color representation with hex value, shape/size styling, text display toggle, and copy affordance. */
+/**
+ * Image dimensions representation displaying formatted width and height in pixels.
+ *
+ * @remarks
+ * Displays a width/height pair as image dimensions. Both values are positive pixel counts; together they describe dimensions, not an aspect ratio or a resize request.
+ */
+export interface DimensionsElement extends UiElementBase {
+    /**
+     * Discriminator type
+     *
+     * @defaultValue "dimensions"
+     */
+    readonly type: "dimensions";
+    /**
+     * Width in pixels
+     *
+     * @remarks
+     * Horizontal pixel count. Values below one are rejected by the schema constraint.
+     */
+    readonly width: number;
+    /**
+     * Height in pixels
+     *
+     * @remarks
+     * Vertical pixel count. Values below one are rejected by the schema constraint.
+     */
+    readonly height: number;
+    /** Optional visual modifiers (copyable) */
+    readonly modifiers?: BaseModifiers;
+}
+/**
+ * Single color representation with hex value, shape/size styling, text display toggle, and copy affordance.
+ *
+ * @remarks
+ * Displays one color swatch with configurable geometry and optional adjacent text. Supply the color as a hexadecimal string; the schema leaves exact accepted hex formats to the renderer.
+ */
 export interface ColourElement extends UiElementBase {
     /**
      * Discriminator type
@@ -269,32 +538,56 @@ export interface ColourElement extends UiElementBase {
      * @defaultValue "color"
      */
     readonly type: "color";
-    /** Hexadecimal color code */
+    /**
+     * Hexadecimal color code
+     *
+     * @remarks
+     * Color value used to draw the swatch. Use a hexadecimal representation supported by the client renderer.
+     */
     readonly value: string;
-    /** Optional descriptive color name label */
+    /**
+     * Optional descriptive color name label
+     *
+     * @remarks
+     * Human-readable color name available to the renderer when text is shown.
+     */
     readonly label?: string;
     /**
      * Whether to display the textual color code or label next to the swatch
      *
+     * @remarks
+     * When true, allows the renderer to show the color's text label alongside the swatch. The default is true.
+     *
      * @defaultValue true
      */
     readonly showText?: boolean;
     /**
      * Visual shape of the color indicator
      *
+     * @remarks
+     * Geometry used for the swatch; defaults to a circle.
+     *
      * @defaultValue Shape.circle
      */
     readonly shape?: Shape;
     /**
      * Visual size of the color indicator
      *
+     * @remarks
+     * Relative size class for the swatch; defaults to medium.
+     *
      * @defaultValue Size.medium
      */
     readonly size?: Size;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     readonly modifiers?: PrimitiveModifiers;
 }
-/** Plain unbounded numeric value primitive element. */
+/**
+ * Plain unbounded numeric value primitive element.
+ *
+ * @remarks
+ * Displays a numeric value without a progress scale or rating interpretation. Use unit to communicate the measurement context; no range is imposed by this model.
+ */
 export interface NumberUnboundedElement extends UiElementBase {
     /**
      * Discriminator type
@@ -302,14 +595,29 @@ export interface NumberUnboundedElement extends UiElementBase {
      * @defaultValue "number-unbounded"
      */
     readonly type: "number-unbounded";
-    /** Numeric value */
+    /**
+     * Numeric value
+     *
+     * @remarks
+     * Number to display. Its meaning and any valid range are defined by the producing feature.
+     */
     readonly value: number;
-    /** Optional unit suffix (e.g. "px", "ms", "MB") */
+    /**
+     * Optional unit suffix (e.g. "px", "ms", "MB")
+     *
+     * @remarks
+     * Short unit label appended or otherwise associated with the displayed value. Include only the unit text, not a second copy of the number.
+     */
     readonly unit?: string;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     readonly modifiers?: PrimitiveModifiers;
 }
-/** Bounded numeric rating represented as visual stars. */
+/**
+ * Bounded numeric rating represented as visual stars.
+ *
+ * @remarks
+ * Displays a score on a star scale. Keep value within the scale from zero through maximum; this model declares the scale metadata but does not impose a numeric validation bound.
+ */
 export interface NumberBoundedStarsElement extends UiElementBase {
     /**
      * Discriminator type
@@ -317,14 +625,29 @@ export interface NumberBoundedStarsElement extends UiElementBase {
      * @defaultValue "number-stars"
      */
     readonly type: "number-stars";
-    /** Numeric rating score */
+    /**
+     * Numeric rating score
+     *
+     * @remarks
+     * Score represented by the filled portion of the star display.
+     */
     readonly value: number;
-    /** Maximum rating scale (defaults to 5) */
+    /**
+     * Maximum rating scale (defaults to 5)
+     *
+     * @remarks
+     * Upper end of the rating scale. When omitted, the scale is five; value should use the same scale.
+     */
     readonly maximum?: number;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     readonly modifiers?: PrimitiveModifiers;
 }
-/** Bounded numeric meter representation (read-only progress / score bar). */
+/**
+ * Bounded numeric meter representation (read-only progress / score bar).
+ *
+ * @remarks
+ * Displays a scalar value against a minimum-to-maximum range. Supply comparable bounds and a value in that range; optional label and unit customize the textual readout without changing the meter scale.
+ */
 export interface NumberBoundedMeterElement extends UiElementBase {
     /**
      * Discriminator type
@@ -332,56 +655,96 @@ export interface NumberBoundedMeterElement extends UiElementBase {
      * @defaultValue "number-meter"
      */
     readonly type: "number-meter";
-    /** Numeric value */
+    /**
+     * Numeric value
+     *
+     * @remarks
+     * Current measurement or score represented by the meter.
+     */
     readonly value: number;
-    /** Minimum scale bound (defaults to 0) */
+    /**
+     * Minimum scale bound (defaults to 0)
+     *
+     * @remarks
+     * Lower end of the meter range. Defaults to zero when omitted.
+     */
     readonly minimum?: number;
-    /** Maximum scale bound (e.g. 100) */
+    /**
+     * Maximum scale bound (e.g. 100)
+     *
+     * @remarks
+     * Upper end of the meter range. Choose a bound consistent with value and minimum.
+     */
     readonly maximum?: number;
-    /** Optional custom text label override (e.g. "68 / 100") */
+    /**
+     * Optional custom text label override (e.g. "68 / 100")
+     *
+     * @remarks
+     * Optional readout text to use instead of a renderer-generated value and range label.
+     */
     readonly label?: string;
-    /** Optional unit suffix (e.g. "%") */
+    /**
+     * Optional unit suffix (e.g. "%")
+     *
+     * @remarks
+     * Unit associated with the value, such as a percent sign. This affects display only and does not convert the numeric value.
+     */
     readonly unit?: string;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     readonly modifiers?: PrimitiveModifiers;
 }
-/** Plain boolean value representation (textual "true" / "false"). */
-export interface BooleanPlainElement extends UiElementBase {
+/**
+ * Boolean value primitive with text or badge presentation.
+ *
+ * @remarks
+ * Displays a boolean state using text or a badge. The representation determines whether true/false labels or a colored badge are used; configured labels and variant are presentation choices only.
+ */
+export interface BooleanElement extends UiElementBase {
     /**
      * Discriminator type
      *
-     * @defaultValue "boolean-plain"
+     * @defaultValue "boolean"
      */
-    readonly type: "boolean-plain";
-    /** Boolean state value */
-    readonly value: boolean;
-    /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
-    readonly modifiers?: PrimitiveModifiers;
-}
-/** Visual badge pill representation of a boolean state. */
-export interface BooleanBadgeElement extends UiElementBase {
+    readonly type: "boolean";
     /**
-     * Discriminator type
+     * Boolean state value
      *
-     * @defaultValue "boolean-badge"
+     * @remarks
+     * State to display. This remains a boolean value in the data model even when the renderer substitutes custom labels.
      */
-    readonly type: "boolean-badge";
-    /** Boolean state value */
     readonly value: boolean;
+    /**
+     * Display representation mode
+     *
+     * @remarks
+     * Selects ordinary text or a badge pill. Badge color applies only to badge presentation.
+     *
+     * @defaultValue BooleanRepresentation.plain
+     */
+    readonly representation?: BooleanRepresentation;
     /**
      * Custom display label when true (defaults to "true")
      *
+     * @remarks
+     * Text used for the true state in plain representation. Defaults to the literal text true.
+     *
      * @defaultValue "true"
      */
     readonly trueLabel?: string;
     /**
      * Custom display label when false (defaults to "false")
      *
+     * @remarks
+     * Text used for the false state in plain representation. Defaults to the literal text false.
+     *
      * @defaultValue "false"
      */
     readonly falseLabel?: string;
     /**
-     * Badge color tone
+     * Badge color tone when rendered as badge
+     *
+     * @remarks
+     * Semantic color treatment for badge presentation; it has no effect in plain representation.
      *
      * @defaultValue BadgeVariant.neutral
      */
@@ -389,7 +752,12 @@ export interface BooleanBadgeElement extends UiElementBase {
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     readonly modifiers?: PrimitiveModifiers;
 }
-/** Formatted date and time representation. */
+/**
+ * Formatted date and time representation.
+ *
+ * @remarks
+ * Displays an epoch timestamp using a selected date/time format. The input is a count of milliseconds, not seconds; relative formatting is interpreted by the consumer.
+ */
 export interface TimestampElement extends UiElementBase {
     /**
      * Discriminator type
@@ -397,18 +765,31 @@ export interface TimestampElement extends UiElementBase {
      * @defaultValue "timestamp"
      */
     readonly type: "timestamp";
-    /** The timestamp in milliseconds */
+    /**
+     * The timestamp in milliseconds
+     *
+     * @remarks
+     * Unix epoch timestamp measured in milliseconds. Convert seconds-based timestamps before assigning this value.
+     */
     readonly value: number;
     /**
      * Presentation date/time format
      *
+     * @remarks
+     * Controls whether the timestamp is shown as date and time, date only, time only, or relative text. The default is datetime.
+     *
      * @defaultValue TimestampFormat.datetime
      */
     readonly format?: TimestampFormat;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     readonly modifiers?: PrimitiveModifiers;
 }
-/** Thumbnail image reference with placeholder fallback handling. */
+/**
+ * Thumbnail image reference with placeholder fallback handling.
+ *
+ * @remarks
+ * References an image source for thumbnail rendering and provides accessible text and a fallback source. The client determines loading, sizing, and placeholder behavior.
+ */
 export interface ImageReferenceElement extends UiElementBase {
     /**
      * Discriminator type
@@ -416,20 +797,43 @@ export interface ImageReferenceElement extends UiElementBase {
      * @defaultValue "image-ref"
      */
     readonly type: "image-ref";
-    /** Image source URI (HTTPS URL, base64 data URI, or asset path) */
+    /**
+     * Image source URI (HTTPS URL, base64 data URI, or asset path)
+     *
+     * @remarks
+     * Source URI understood by the client renderer. Supported forms include HTTPS locations, base64 data URIs, and client asset paths; this field is not raw image bytes.
+     */
     readonly src: string;
-    /** Accessible alternative description */
+    /**
+     * Accessible alternative description
+     *
+     * @remarks
+     * Alternative text describing the image for assistive technology. Provide meaningful text when the image conveys information; omit it only when it is decorative.
+     */
     readonly alt?: string;
     /**
      * Aspect ratio of the thumbnail container
      *
+     * @remarks
+     * Preferred ratio of the rendered thumbnail container, expressed as a ratio string such as 1:1. It controls presentation rather than modifying the source image.
+     *
      * @defaultValue "1:1"
      */
     readonly aspectRatio?: string;
-    /** Fallback placeholder image URI */
+    /**
+     * Fallback placeholder image URI
+     *
+     * @remarks
+     * Optional source to display when the primary image cannot be loaded. It follows the same URI conventions as src.
+     */
     readonly placeholder?: string;
 }
-/** Interactive button action triggering an extension command. */
+/**
+ * Interactive button action triggering an extension command.
+ *
+ * @remarks
+ * When activated, the client dispatches commandId to the specified extension and may include target and parameters as command input. disabled and variant affect presentation and availability, not the command's authorization.
+ */
 export interface ButtonActionElement extends UiActionBase {
     /**
      * Discriminator type
@@ -437,28 +841,59 @@ export interface ButtonActionElement extends UiActionBase {
      * @defaultValue "button"
      */
     readonly type: "button";
-    /** Extension identifier owning the target command */
+    /**
+     * Extension identifier owning the target command
+     *
+     * @remarks
+     * Extension that registers commandId. Omit only when the client can resolve the command in the current extension context.
+     */
     readonly extensionId?: string;
-    /** Command identifier to invoke */
+    /**
+     * Command identifier to invoke
+     *
+     * @remarks
+     * Identifier of the registered extension command to dispatch when the button is activated.
+     */
     readonly commandId: string;
-    /** Target entity or context identifier */
+    /**
+     * Target entity or context identifier
+     *
+     * @remarks
+     * Optional entity or context identifier forwarded to the command handler. Its format is determined by the target extension.
+     */
     readonly target?: string;
-    /** Optional arbitrary parameters payload forwarded to the command handler */
+    /**
+     * Optional arbitrary parameters payload forwarded to the command handler
+     *
+     * @remarks
+     * JSON-compatible arguments passed to the extension command. Define and validate their shape in the command implementation.
+     */
     readonly parameters?: Record<string, unknown>;
     /**
      * Whether the button is disabled / unavailable
      *
+     * @remarks
+     * When true, the client renders the action as unavailable and should not dispatch it from user activation.
+     *
      * @defaultValue false
      */
     readonly disabled?: boolean;
     /**
      * Button visual style variant
      *
+     * @remarks
+     * Selects the button's emphasis style. Use danger for destructive operations and primary for the main recommended action; the variant does not change behavior.
+     *
      * @defaultValue ButtonVariant.secondary
      */
     readonly variant?: ButtonVariant;
 }
-/** External link action distinct from inline URL text values. */
+/**
+ * External link action distinct from inline URL text values.
+ *
+ * @remarks
+ * Renders a user-invokable action that opens a destination externally. Use StringUrlElement for a link embedded in content rather than an action control.
+ */
 export interface ExternalLinkActionElement extends UiActionBase {
     /**
      * Discriminator type
@@ -466,10 +901,20 @@ export interface ExternalLinkActionElement extends UiActionBase {
      * @defaultValue "external-link"
      */
     readonly type: "external-link";
-    /** Target URL destination */
+    /**
+     * Target URL destination
+     *
+     * @remarks
+     * External destination opened when the user activates the link action. The client controls how external navigation is handed to the platform.
+     */
     readonly url: string;
 }
-/** Full Markdown fallback block rendered with core typographic hierarchy, spacing, and styling. */
+/**
+ * Full Markdown fallback block rendered with core typographic hierarchy, spacing, and styling.
+ *
+ * @remarks
+ * Use this custom-renderer escape hatch when the structured ViewKit elements cannot express the required rich text. Markdown rendering is a presentation fallback; prefer typed elements when consumers need to inspect individual values.
+ */
 export interface MarkdownBlockElement extends UiElementBase {
     /**
      * Discriminator type
@@ -477,12 +922,22 @@ export interface MarkdownBlockElement extends UiElementBase {
      * @defaultValue "markdown"
      */
     readonly type: "markdown";
-    /** Raw Markdown markup content */
+    /**
+     * Raw Markdown markup content
+     *
+     * @remarks
+     * Markdown source consumed by the client renderer. The schema treats it as an opaque string and does not validate the markup or its links.
+     */
     readonly content: string;
     /** Optional visual modifiers (copyable) */
     readonly modifiers?: BaseModifiers;
 }
-/** Sandboxed HTML rendering escape hatch. */
+/**
+ * Sandboxed HTML rendering escape hatch.
+ *
+ * @remarks
+ * Use only when structured elements or Markdown cannot represent the required content. Rendering occurs in a sandboxed host context, but callers should still avoid embedding untrusted content and should not assume access to application privileges.
+ */
 export interface HtmlBlockElement extends UiElementBase {
     /**
      * Discriminator type
@@ -490,23 +945,50 @@ export interface HtmlBlockElement extends UiElementBase {
      * @defaultValue "html"
      */
     readonly type: "html";
-    /** Raw HTML markup content */
+    /**
+     * Raw HTML markup content
+     *
+     * @remarks
+     * HTML source passed to the custom renderer. This is an opaque string, not a typed or sanitized DOM structure.
+     */
     readonly content: string;
     /** Optional visual modifiers (copyable) */
     readonly modifiers?: BaseModifiers;
 }
-/** Single slot within a multi-slot horizontal row layout. */
+/**
+ * Single slot within a multi-slot horizontal row layout.
+ *
+ * @remarks
+ * A slot combines an optional label, a relative width, and one visual child. Slot widths are percentages of the row and should be chosen so the full row's widths form a usable layout.
+ */
 export interface Slot {
-    /** Optional slot label (e.g. "Slot A") */
+    /**
+     * Optional slot label (e.g. "Slot A")
+     *
+     * @remarks
+     * Short text identifying this region of the row. It is independent of the rendered content.
+     */
     readonly label?: string;
-    /** Relative or fractional width proportion (e.g. "1/3", "2/3", "100px", "auto") */
-    readonly width?: string;
-    /** Rendered content inside the slot */
+    /**
+     * Width percentage (1-100)
+     *
+     * @remarks
+     * Relative share of the row width. The schema constrains explicit values to the inclusive range 1 through 100.
+     */
+    readonly width?: number;
+    /**
+     * Rendered content inside the slot
+     *
+     * @remarks
+     * One visual element displayed in this slot. Use a nested layout element when the slot itself needs multiple children.
+     */
     readonly content: UiElement;
 }
 /**
- * Multi-slot horizontal row with declared column width proportions.
- * Examples: "1/3 + 2/3", "equal thirds", "1/4 + 3/4".
+ * Horizontal row layout with individually sized slots.
+ *
+ * @remarks
+ * Use this layout when a row needs explicit regions with independently controlled widths. Each slot contains one child element; unlike FlowingElement, the layout does not automatically wrap a sequence of children.
  */
 export interface MultiSlotElement extends UiElementBase {
     /**
@@ -515,14 +997,19 @@ export interface MultiSlotElement extends UiElementBase {
      * @defaultValue "multi-slot"
      */
     readonly type: "multi-slot";
-    /** Proportions descriptor (e.g. "1/3 + 2/3", "equal", "1/4 + 3/4") */
-    readonly proportions?: string;
-    /** List of slots comprising the row */
+    /**
+     * List of slots comprising the row
+     *
+     * @remarks
+     * Ordered slots in the row. Each slot's width is a percentage; arrange slot definitions in the intended visual order.
+     */
     readonly slots: Slot[];
 }
 /**
- * Flowing inline layout container with automatic line wrapping.
- * Renders child elements horizontally in sequence, automatically wrapping to the next line when space runs out.
+ * Inline layout container that wraps child elements.
+ *
+ * @remarks
+ * Use for compact related values that should flow horizontally and wrap naturally at the available width. Child order is preserved; an optional separator is placed between neighboring children.
  */
 export interface FlowingElement extends UiElementBase {
     /**
@@ -531,12 +1018,26 @@ export interface FlowingElement extends UiElementBase {
      * @defaultValue "flowing"
      */
     readonly type: "flowing";
-    /** List of child elements rendered sequentially with line wrapping */
+    /**
+     * Optional visual separator rendered between sequential child elements
+     *
+     * @remarks
+     * Separator placed between adjacent elements. Omit it when spacing or the child renderers already provide sufficient separation.
+     */
+    readonly separator?: Separator;
+    /**
+     * List of child elements rendered sequentially with line wrapping
+     *
+     * @remarks
+     * Ordered children rendered in the flow. The client wraps them as needed rather than requiring callers to calculate line breaks.
+     */
     readonly elements: UiElement[];
 }
 /**
- * Standard label and value row.
- * Displays a muted label on the left and value representation on the right with a vertical dividing line.
+ * Label and value row with an optional divider.
+ *
+ * @remarks
+ * Represents one named value with a muted left-hand label and a right-hand visual element. Use it for a single field; use TableElement for repeated rows or column-aligned data.
  */
 export interface LabelValueElement extends UiElementBase {
     /**
@@ -545,38 +1046,90 @@ export interface LabelValueElement extends UiElementBase {
      * @defaultValue "label-value"
      */
     readonly type: "label-value";
-    /** Key or descriptive label displayed muted on the left */
+    /**
+     * Key or descriptive label displayed muted on the left
+     *
+     * @remarks
+     * Human-readable name for the value. This text is rendered as the row label rather than as a separate UiElement.
+     */
     readonly label: string;
-    /** Rendered value element on the right */
+    /**
+     * Rendered value element on the right
+     *
+     * @remarks
+     * Value content rendered in the right-hand region. It may be a primitive or a nested structural element.
+     */
     readonly value: UiElement;
     /**
      * Whether to render a bottom border/hairline divider
      *
+     * @remarks
+     * Enables a horizontal separator beneath this row when true. Defaults to false.
+     *
      * @defaultValue false
      */
     readonly withDivider?: boolean;
 }
-/** Column definition for structured tables. */
+/**
+ * Column definition for structured tables.
+ *
+ * @remarks
+ * Describes one table column and its visual sizing. When columns are supplied, their order corresponds to the position of each cell in a row.
+ */
 export interface TableColumn {
-    /** Display header text */
+    /**
+     * Display header text
+     *
+     * @remarks
+     * Optional header shown above values in this column. Omit when the table has no header row.
+     */
     readonly header?: string;
     /**
      * Text horizontal alignment
      *
+     * @remarks
+     * Horizontal alignment applied to cell content in the column. Defaults to left.
+     *
      * @defaultValue TableColumnAlign.left
      */
     readonly align?: TableColumnAlign;
-    /** Optional width constraint */
-    readonly width?: string;
+    /**
+     * Width percentage (1-100)
+     *
+     * @remarks
+     * Column width percentage used with widthMode. Explicit values are constrained to 1 through 100.
+     */
+    readonly width?: number;
+    /**
+     * Sizing mode for the provided width
+     *
+     * @remarks
+     * Determines whether width is a fixed percentage allocation or an upper bound. Defaults to fixed.
+     *
+     * @defaultValue TableColumnWidthMode.fixed
+     */
+    readonly widthMode?: TableColumnWidthMode;
 }
-/** Single table row containing an array of cell values. */
+/**
+ * Single table row containing an array of cell values.
+ *
+ * @remarks
+ * A row's cell array is positional: cell at each index corresponds to the column at that index. Keep row lengths aligned with the table's explicit column definitions when present.
+ */
 export interface TableRow {
-    /** Array of cell values corresponding to table columns */
+    /**
+     * Array of cell values corresponding to table columns
+     *
+     * @remarks
+     * Ordered contents for this row. Each cell is a UiElement so values can use the same primitive and layout renderers as other ViewKit content.
+     */
     readonly cells: UiElement[];
 }
 /**
- * Structured tabular data representation.
- * Supports header/borderless modes, 2-column key-value tables, and 3-column data tables.
+ * Structured tabular data with optional columns and separators.
+ *
+ * @remarks
+ * Use for data that benefits from aligned rows and columns, including key/value and multi-column tables. Supply rows in display order; explicit columns are optional, and divider/striping flags independently control visual separators and alternating backgrounds.
  */
 export interface TableElement extends UiElementBase {
     /**
@@ -585,45 +1138,83 @@ export interface TableElement extends UiElementBase {
      * @defaultValue "table"
      */
     readonly type: "table";
-    /**
-     * Whether to render a column header row
-     *
-     * @defaultValue true
-     */
-    readonly hasHeader?: boolean;
     /**
      * Whether to render alternating row background colors
      *
+     * @remarks
+     * Enables alternating backgrounds across successive rows to improve scanability. Defaults to false.
+     *
      * @defaultValue false
      */
     readonly isStriped?: boolean;
     /**
      * Whether to render vertical column separators
      *
+     * @remarks
+     * Adds vertical dividers between columns when true. Defaults to false.
+     *
      * @defaultValue false
      */
     readonly withColumnSeparators?: boolean;
     /**
      * Whether to render horizontal row separators
      *
+     * @remarks
+     * Adds horizontal dividers between rows when true. Defaults to false.
+     *
      * @defaultValue false
      */
     readonly withRowSeparators?: boolean;
-    /** Optional explicit column definitions */
+    /**
+     * Optional explicit column definitions
+     *
+     * @remarks
+     * Optional ordered column metadata defining headers, alignment, and width. When omitted, the renderer may infer a basic layout from row cells.
+     */
     readonly columns?: TableColumn[];
-    /** Tabular data rows */
+    /**
+     * Tabular data rows
+     *
+     * @remarks
+     * Ordered table rows. Each row's cells correspond positionally to the declared columns.
+     */
     readonly rows: TableRow[];
 }
-/** Single entry within a repeating group. */
+/**
+ * Single entry within a repeating group.
+ *
+ * @remarks
+ * A repeating entry carries a stable display label and either one primary value or a list of nested elements, depending on the shape needed by the feature.
+ */
 export interface RepeatingGroupEntry {
-    /** Entry label */
+    /**
+     * Entry label
+     *
+     * @remarks
+     * Short label identifying this entry within the repeated group.
+     */
     readonly label: string;
-    /** Primary entry value or nested elements */
+    /**
+     * Primary entry value or nested elements
+     *
+     * @remarks
+     * Optional primary visual value for a compact entry. Use elements for a multi-part structured entry.
+     */
     readonly value?: UiElement;
-    /** Nested elements for structured entries */
+    /**
+     * Nested elements for structured entries
+     *
+     * @remarks
+     * Optional ordered content for entries that require more than one value element.
+     */
     readonly elements?: UiElement[];
 }
-/** Repeating group container where entries share uniform structure and retain per-entry labels. */
+/**
+ * Repeating group container where entries share uniform structure and retain per-entry labels.
+ *
+ * @remarks
+ * Groups a sequence of labeled entries under one optional section title. Use it when records have the same general presentation but need their own labels.
+ */
 export interface RepeatingGroupElement extends UiElementBase {
     /**
      * Discriminator type
@@ -631,12 +1222,27 @@ export interface RepeatingGroupElement extends UiElementBase {
      * @defaultValue "repeating-group"
      */
     readonly type: "repeating-group";
-    /** Optional section header for the group */
+    /**
+     * Optional section header for the group
+     *
+     * @remarks
+     * Heading displayed for the repeated section, separate from the labels of individual entries.
+     */
     readonly title?: string;
-    /** List of repeated entry records */
+    /**
+     * List of repeated entry records
+     *
+     * @remarks
+     * Entries in display order. Each entry supplies its own label and content.
+     */
     readonly entries: RepeatingGroupEntry[];
 }
-/** Collapsible disclosure container (accordion) with summary badge. */
+/**
+ * Collapsible disclosure container (accordion) with summary badge.
+ *
+ * @remarks
+ * Groups nested content behind a disclosure control. The title names the group, summary can provide a compact status indicator, and defaultExpanded controls only the initial state.
+ */
 export interface CollapsibleGroupElement extends UiElementBase {
     /**
      * Discriminator type
@@ -644,20 +1250,43 @@ export interface CollapsibleGroupElement extends UiElementBase {
      * @defaultValue "collapsible-group"
      */
     readonly type: "collapsible-group";
-    /** Group title (e.g. "Show specimen details") */
+    /**
+     * Group title (e.g. "Show specimen details")
+     *
+     * @remarks
+     * Text shown on the disclosure control. Use a concise action or section name that remains meaningful while the content is collapsed.
+     */
     readonly title: string;
-    /** Secondary summary indicator (e.g. "2 neutral values") */
+    /**
+     * Secondary summary indicator (e.g. "2 neutral values")
+     *
+     * @remarks
+     * Compact contextual text shown alongside the title while the group is collapsed or expanded. It does not replace the nested content.
+     */
     readonly summary?: string;
     /**
      * Whether the disclosure is open/expanded by default
      *
+     * @remarks
+     * Initial expanded state requested by the data. Defaults to false; subsequent interaction is managed by the client.
+     *
      * @defaultValue false
      */
     readonly defaultExpanded?: boolean;
-    /** Nested content elements revealed when expanded */
+    /**
+     * Nested content elements revealed when expanded
+     *
+     * @remarks
+     * Ordered child elements made visible by expanding the group.
+     */
     readonly elements: UiElement[];
 }
-/** Visual hairline separator separating sections or element groups. */
+/**
+ * Visual hairline separator separating sections or element groups.
+ *
+ * @remarks
+ * A standalone visual separator for dividing adjacent sections or element groups. Use the divider flags on tables or rows when the separator is part of that structure.
+ */
 export interface DividerElement extends UiElementBase {
     /**
      * Discriminator type
@@ -668,56 +1297,108 @@ export interface DividerElement extends UiElementBase {
     /**
      * Line styling
      *
+     * @remarks
+     * Visual stroke treatment for the separator. Defaults to a subtle hairline.
+     *
      * @defaultValue DividerStyle.hairline
      */
     readonly style?: DividerStyle;
 }
-/** Base envelope container model holding the schema version attribute. */
+/**
+ * Base envelope containing the schema version.
+ *
+ * @remarks
+ * All root ViewKit documents extend this envelope so consumers can identify the schema contract version before processing the root content.
+ */
 export interface Envelop {
     /**
      * Schema specification version
      *
+     * @remarks
+     * Version of the ViewKit envelope contract. It is a literal value and should be preserved when serializing or forwarding a document.
+     *
      * @defaultValue "1.0"
      */
     readonly schemaVersion: "1.0";
 }
-/** Container model representing an ordered list of visual elements. */
+/**
+ * Root container holding an ordered list of visual elements.
+ *
+ * @remarks
+ * Provides the shared root content collection inherited by cards and other root models. The order of elements is significant and is preserved by the renderer.
+ */
 export interface UiContainer extends Envelop {
-    /** Ordered list of visual elements, structures, and content */
+    /**
+     * Ordered list of visual elements, structures, and content
+     *
+     * @remarks
+     * Top-level visual content in render order. Use a structural element to group related children and primitive elements for individual values.
+     */
     readonly elements: UiElement[];
 }
 /**
- * Root Card container model.
- * Represents a complete feature card rendered inside the 360px panel.
+ * Root container for a complete feature card.
+ *
+ * @remarks
+ * A complete card has a required title and ordered content inherited from UiContainer. It is designed for the feature-card surface; description and actions supplement the content, with action controls rendered separately from the element list.
  */
 export interface UiCard extends UiContainer {
-    /** Human-readable feature title displayed in the card header */
+    /**
+     * Human-readable feature title displayed in the card header
+     *
+     * @remarks
+     * Primary heading for the card. Keep it concise enough for the card header; longer explanatory text belongs in description or elements.
+     */
     readonly title: string;
-    /** Optional neutral subtitle / description for the feature */
+    /**
+     * Optional neutral subtitle / description for the feature
+     *
+     * @remarks
+     * Brief secondary context shown with the title. Use the content elements for detailed information rather than placing an entire report in this field.
+     */
     readonly description?: string;
-    /** Optional card action buttons rendered at the base of the feature card */
+    /**
+     * Optional card action buttons rendered at the base of the feature card
+     *
+     * @remarks
+     * Optional user-invokable actions shown after the card content. Their order is preserved and each action's own fields define its command or link behavior.
+     */
     readonly actions?: UiAction[];
 }
 /**
- * Polymorphic root base model for all visual UI elements in Picteus feature views.
- * Uses the @discriminator("type") decorator so all child models inheriting from UiElement
- * are automatically recognized by schema emitters and SDK code generators.
+ * Polymorphic root model for visual UI elements.
+ *
+ * @remarks
+ * Every concrete visual element carries a type discriminator whose literal value selects its model and renderer. The @discriminator("type") metadata lets schema emitters and SDK generators represent derived models as a polymorphic hierarchy. Consumers should dispatch on the discriminator and preserve unknown elements when round-tripping data where possible.
+ */
+export type UiElement = StringElement | StringsElement | StringCodeElement | XmlElement | JsonElement | StringUrlElement | IdentifierElement | RatioElement | DimensionsElement | ColourElement | NumberUnboundedElement | NumberBoundedStarsElement | NumberBoundedMeterElement | BooleanElement | TimestampElement | ImageReferenceElement | MarkdownBlockElement | HtmlBlockElement | MultiSlotElement | FlowingElement | LabelValueElement | TableElement | RepeatingGroupElement | CollapsibleGroupElement | DividerElement;
+/**
+ * Polymorphic base model for interactive actions.
+ *
+ * @remarks
+ * Shared action contract for user-invokable card controls. Concrete action models provide their own discriminator and action-specific destination or command fields.
  */
-export type UiElement = StringShortElement | StringLongElement | StringCodeElement | XmlElement | JsonElement | StringUrlElement | IdentifierElement | RatioElement | ColourElement | NumberUnboundedElement | NumberBoundedStarsElement | NumberBoundedMeterElement | BooleanPlainElement | BooleanBadgeElement | TimestampElement | ImageReferenceElement | MarkdownBlockElement | HtmlBlockElement | MultiSlotElement | FlowingElement | LabelValueElement | TableElement | RepeatingGroupElement | CollapsibleGroupElement | DividerElement;
-/** Polymorphic base model for interactive actions. */
 export type UiAction = ButtonActionElement | ExternalLinkActionElement;
 /**
  * Class implementation of the `TruncateOptions` interface.
  *
  * @remarks
- * Truncation configuration for long textual content with optional expand affordance.
+ * Controls how a renderer abbreviates long text. The character limit is a presentation threshold rather than a validation limit; showMore lets the user reveal the remaining text.
  */
 export declare class TruncateOptionsClass extends ViewKitNode<TruncateOptions> implements TruncateOptions {
-    /** Maximum number of characters to display before truncating */
+    /**
+     * Maximum number of characters to display before truncating
+     *
+     * @remarks
+     * Threshold after which the renderer can shorten the displayed text. This does not constrain the stored string or remove its undisplayed content.
+     */
     readonly characterLimit: number;
     /**
      * Whether to render a "Show more" / "Show less" toggle affordance
      *
+     * @remarks
+     * When true, permits an expand/collapse control for text beyond the truncation threshold. Defaults to true.
+     *
      * @defaultValue true
      */
     readonly showMore?: boolean;
@@ -725,6 +1406,8 @@ export declare class TruncateOptionsClass extends ViewKitNode<TruncateOptions> i
      * Constructs a new `TruncateOptionsClass` instance.
      *
      * @param characterLimit - Maximum number of characters to display before truncating
+  
+    Threshold after which the renderer can shorten the displayed text. This does not constrain the stored string or remove its undisplayed content.
      * @param options - Optional component settings. (showMore (defaults to `true`)).
      */
     constructor(characterLimit: number, options?: {
@@ -735,10 +1418,15 @@ export declare class TruncateOptionsClass extends ViewKitNode<TruncateOptions> i
  * Class implementation of the `BaseModifiers` interface.
  *
  * @remarks
- * Base modifier traits for elements that support copy affordance.
+ * Common optional presentation traits shared by primitive values and content renderers. Modifiers affect how content is displayed or copied; they do not transform the source value.
  */
 export declare class BaseModifiersClass extends ViewKitNode<BaseModifiers> implements BaseModifiers {
-    /** Adds an interactive copy button/action next to the rendered value */
+    /**
+     * Adds an interactive copy button/action next to the rendered value
+     *
+     * @remarks
+     * When true, exposes a copy affordance for the associated value where supported by the renderer.
+     */
     readonly copyable?: boolean;
     /**
      * Constructs a new `BaseModifiersClass` instance.
@@ -753,30 +1441,49 @@ export declare class BaseModifiersClass extends ViewKitNode<BaseModifiers> imple
  * Class implementation of the `PrimitiveModifiers` interface.
  *
  * @remarks
- * Common modifier traits that can be attached to primitive elements.
+ * Extends BaseModifiers with text styling controls. Defaults provide normal weight, medium intensity, and proportional text unless a feature explicitly overrides them.
  */
 export declare class PrimitiveModifiersClass extends ViewKitNode<PrimitiveModifiers> implements PrimitiveModifiers {
-    /** Configures character truncation threshold with show-more affordance */
+    /**
+     * Configures character truncation threshold with show-more affordance
+     *
+     * @remarks
+     * Optional text abbreviation behavior. The source text remains unchanged, and the renderer may offer expansion according to showMore.
+     */
     readonly truncate?: TruncateOptions;
     /**
      * Typographic text weight
      *
+     * @remarks
+     * Relative font weight for textual rendering; defaults to normal.
+     *
      * @defaultValue TextWeight.normal
      */
     readonly weight?: TextWeight;
     /**
      * Visual text color intensity
      *
+     * @remarks
+     * Relative contrast treatment for the text; defaults to medium.
+     *
      * @defaultValue TextIntensity.medium
      */
     readonly intensity?: TextIntensity;
     /**
      * Whether to use monospace font rendering (for hashes, IDs, codes)
      *
+     * @remarks
+     * When true, requests a fixed-width font suitable for identifiers and code-like values. Defaults to false.
+     *
      * @defaultValue false
      */
     readonly monospace?: boolean;
-    /** Adds an interactive copy button/action next to the rendered value */
+    /**
+     * Adds an interactive copy button/action next to the rendered value
+     *
+     * @remarks
+     * When true, exposes a copy affordance for the associated value where supported by the renderer.
+     */
     readonly copyable?: boolean;
     /**
      * Constructs a new `PrimitiveModifiersClass` instance.
@@ -792,64 +1499,98 @@ export declare class PrimitiveModifiersClass extends ViewKitNode<PrimitiveModifi
     });
 }
 /**
- * Class implementation of the `StringShortElement` interface.
+ * Class implementation of the `StringElement` interface.
  *
  * @remarks
- * Short string primitive element.
- * Supports plain text or compact chip pill presentation.
+ * Use this primitive for one textual value when a structured label/value row is unnecessary. Choose multiline for content whose line breaks should remain visible; modifiers apply presentation traits without changing the underlying value.
  */
-export declare class StringShortElementClass extends BaseUiElement<StringShortElement> implements StringShortElement {
+export declare class StringElementClass extends BaseUiElement<StringElement> implements StringElement {
+    /**
+     * Discriminator identifier for `StringElement`.
+     *
+     * @defaultValue "string"
+     */
+    readonly type = "string";
     /**
-     * Discriminator identifier for `StringShortElement`.
+     * Text value
      *
-     * @defaultValue "string-short"
+     * @remarks
+     * Text to render. Supply plain text; this field is not a Markdown or HTML document.
      */
-    readonly type = "string-short";
-    /** Text value */
     readonly value: string;
     /**
      * Display representation mode
      *
-     * @defaultValue StringShortRepresentation.plain
+     * @remarks
+     * Selects inline, chip, or multiline rendering. The default is plain, so callers can omit this for ordinary text.
+     *
+     * @defaultValue StringRepresentation.plain
      */
-    readonly representation?: StringShortRepresentation;
+    readonly representation?: StringRepresentation;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     readonly modifiers?: PrimitiveModifiers;
     /**
-     * Constructs a new `StringShortElementClass` instance.
+     * Constructs a new `StringElementClass` instance.
      *
      * @param value - Text value
+  
+    Text to render. Supply plain text; this field is not a Markdown or HTML document.
      * @param options - Optional component settings. (representation (defaults to `plain`), modifiers).
      */
     constructor(value: string, options?: {
-        representation?: StringShortRepresentation;
+        representation?: StringRepresentation;
         modifiers?: PrimitiveModifiers;
     });
 }
 /**
- * Class implementation of the `StringLongElement` interface.
+ * Class implementation of the `StringsElement` interface.
  *
  * @remarks
- * Multiline text block primitive element for descriptions, comments, or prose.
+ * Use this primitive when several related strings should be rendered as one compact sequence. The client preserves the array order and inserts the selected separator between values.
  */
-export declare class StringLongElementClass extends BaseUiElement<StringLongElement> implements StringLongElement {
+export declare class StringsElementClass extends BaseUiElement<StringsElement> implements StringsElement {
     /**
-     * Discriminator identifier for `StringLongElement`.
+     * Discriminator identifier for `StringsElement`.
      *
-     * @defaultValue "string-long"
+     * @defaultValue "strings"
      */
-    readonly type = "string-long";
-    /** Text value */
-    readonly value: string;
+    readonly type = "strings";
+    /**
+     * Array of string values
+     *
+     * @remarks
+     * Values to render in order. Each array entry remains a distinct item for chip presentation and is not parsed as a delimited string.
+     */
+    readonly values: string[];
+    /**
+     * Display representation mode (plain text or visual chips)
+     *
+     * @remarks
+     * Selects whether values appear as ordinary inline text or as separate visual chips. The default uses the plain representation.
+     *
+     * @defaultValue StringRepresentation.plain
+     */
+    readonly representation?: StringRepresentation;
+    /**
+     * Optional visual separator rendered between sequential values
+     *
+     * @remarks
+     * Separator inserted between adjacent values in plain representation. It does not become part of any value.
+     */
+    readonly separator?: Separator;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     readonly modifiers?: PrimitiveModifiers;
     /**
-     * Constructs a new `StringLongElementClass` instance.
+     * Constructs a new `StringsElementClass` instance.
      *
-     * @param value - Text value
-     * @param options - Optional component settings. (modifiers).
+     * @param values - Array of string values
+  
+    Values to render in order. Each array entry remains a distinct item for chip presentation and is not parsed as a delimited string.
+     * @param options - Optional component settings. (representation (defaults to `plain`), separator, modifiers).
      */
-    constructor(value: string, options?: {
+    constructor(values: string[], options?: {
+        representation?: StringRepresentation;
+        separator?: Separator;
         modifiers?: PrimitiveModifiers;
     });
 }
@@ -857,7 +1598,7 @@ export declare class StringLongElementClass extends BaseUiElement<StringLongElem
  * Class implementation of the `StringCodeElement` interface.
  *
  * @remarks
- * Monospace code block or formatted code snippet representation.
+ * Use for source-like or preformatted textual content that should be rendered in a code-oriented style. The language is a presentation hint; the content is not parsed or validated as code by this contract.
  */
 export declare class StringCodeElementClass extends BaseUiElement<StringCodeElement> implements StringCodeElement {
     /**
@@ -866,9 +1607,19 @@ export declare class StringCodeElementClass extends BaseUiElement<StringCodeElem
      * @defaultValue "string-code"
      */
     readonly type = "string-code";
-    /** Text value */
+    /**
+     * Text value
+     *
+     * @remarks
+     * Code or text snippet to display. Include any desired line breaks in this string.
+     */
     readonly value: string;
-    /** Optional syntax highlighting language identifier */
+    /**
+     * Optional syntax highlighting language identifier
+     *
+     * @remarks
+     * Optional syntax hint for the renderer. Supported values describe highlighting modes and do not validate the snippet's syntax.
+     */
     readonly language?: CodeLanguage;
     /** Optional visual modifiers (copyable) */
     readonly modifiers?: BaseModifiers;
@@ -876,6 +1627,8 @@ export declare class StringCodeElementClass extends BaseUiElement<StringCodeElem
      * Constructs a new `StringCodeElementClass` instance.
      *
      * @param value - Text value
+  
+    Code or text snippet to display. Include any desired line breaks in this string.
      * @param options - Optional component settings. (language, modifiers).
      */
     constructor(value: string, options?: {
@@ -887,7 +1640,7 @@ export declare class StringCodeElementClass extends BaseUiElement<StringCodeElem
  * Class implementation of the `XmlElement` interface.
  *
  * @remarks
- * XML markup code block element.
+ * Specialized code-oriented element for XML content. It uses the custom XML renderer rather than requiring consumers to construct a generic code block.
  */
 export declare class XmlElementClass extends BaseUiElement<XmlElement> implements XmlElement {
     /**
@@ -896,7 +1649,12 @@ export declare class XmlElementClass extends BaseUiElement<XmlElement> implement
      * @defaultValue "xml"
      */
     readonly type = "xml";
-    /** XML content value */
+    /**
+     * XML content value
+     *
+     * @remarks
+     * XML markup to render. The contract carries the source text; it does not guarantee that the document is well-formed.
+     */
     readonly value: string;
     /** Optional visual modifiers (copyable) */
     readonly modifiers?: BaseModifiers;
@@ -904,6 +1662,8 @@ export declare class XmlElementClass extends BaseUiElement<XmlElement> implement
      * Constructs a new `XmlElementClass` instance.
      *
      * @param value - XML content value
+  
+    XML markup to render. The contract carries the source text; it does not guarantee that the document is well-formed.
      * @param options - Optional component settings. (modifiers).
      */
     constructor(value: string, options?: {
@@ -914,7 +1674,7 @@ export declare class XmlElementClass extends BaseUiElement<XmlElement> implement
  * Class implementation of the `JsonElement` interface.
  *
  * @remarks
- * JSON data or structure representation element.
+ * Specialized representation for JSON text. Supply serialized JSON when consumers should display a JSON document; this field is a string and is not structurally validated here.
  */
 export declare class JsonElementClass extends BaseUiElement<JsonElement> implements JsonElement {
     /**
@@ -923,7 +1683,12 @@ export declare class JsonElementClass extends BaseUiElement<JsonElement> impleme
      * @defaultValue "json"
      */
     readonly type = "json";
-    /** JSON content value */
+    /**
+     * JSON content value
+     *
+     * @remarks
+     * Serialized JSON text to render. No parsing or schema validation is implied by this element.
+     */
     readonly value: string;
     /** Optional visual modifiers (copyable) */
     readonly modifiers?: BaseModifiers;
@@ -931,6 +1696,8 @@ export declare class JsonElementClass extends BaseUiElement<JsonElement> impleme
      * Constructs a new `JsonElementClass` instance.
      *
      * @param value - JSON content value
+  
+    Serialized JSON text to render. No parsing or schema validation is implied by this element.
      * @param options - Optional component settings. (modifiers).
      */
     constructor(value: string, options?: {
@@ -941,7 +1708,7 @@ export declare class JsonElementClass extends BaseUiElement<JsonElement> impleme
  * Class implementation of the `StringUrlElement` interface.
  *
  * @remarks
- * Hyperlink representation for external or internal URL navigation.
+ * Use this element when displayed text should also behave as a link. Unlike StringElement, the value is a navigation destination and may be paired with a separate human-readable label.
  */
 export declare class StringUrlElementClass extends BaseUiElement<StringUrlElement> implements StringUrlElement {
     /**
@@ -950,7 +1717,12 @@ export declare class StringUrlElementClass extends BaseUiElement<StringUrlElemen
      * @defaultValue "string-url"
      */
     readonly type = "string-url";
-    /** Target URL or navigation destination */
+    /**
+     * Target URL or navigation destination
+     *
+     * @remarks
+     * Destination associated with the link. Supply a URL or client-recognized navigation target supported by the renderer.
+     */
     readonly value: string;
     /** Optional custom anchor text label */
     readonly label?: string;
@@ -960,6 +1732,8 @@ export declare class StringUrlElementClass extends BaseUiElement<StringUrlElemen
      * Constructs a new `StringUrlElementClass` instance.
      *
      * @param value - Target URL or navigation destination
+  
+    Destination associated with the link. Supply a URL or client-recognized navigation target supported by the renderer.
      * @param options - Optional component settings. (label, modifiers).
      */
     constructor(value: string, options?: {
@@ -971,7 +1745,7 @@ export declare class StringUrlElementClass extends BaseUiElement<StringUrlElemen
  * Class implementation of the `IdentifierElement` interface.
  *
  * @remarks
- * Monospace semantic identifier representation.
+ * Use for identifiers, hashes, and other machine-oriented strings that benefit from monospace styling. The value remains text and is not resolved as a Picteus entity.
  */
 export declare class IdentifierElementClass extends BaseUiElement<IdentifierElement> implements IdentifierElement {
     /**
@@ -980,7 +1754,12 @@ export declare class IdentifierElementClass extends BaseUiElement<IdentifierElem
      * @defaultValue "identifier"
      */
     readonly type = "identifier";
-    /** Identifier string value */
+    /**
+     * Identifier string value
+     *
+     * @remarks
+     * Identifier text to display, such as an opaque ID or hash. Avoid embedding presentation markup in the value.
+     */
     readonly value: string;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     readonly modifiers?: PrimitiveModifiers;
@@ -988,6 +1767,8 @@ export declare class IdentifierElementClass extends BaseUiElement<IdentifierElem
      * Constructs a new `IdentifierElementClass` instance.
      *
      * @param value - Identifier string value
+  
+    Identifier text to display, such as an opaque ID or hash. Avoid embedding presentation markup in the value.
      * @param options - Optional component settings. (modifiers).
      */
     constructor(value: string, options?: {
@@ -998,7 +1779,7 @@ export declare class IdentifierElementClass extends BaseUiElement<IdentifierElem
  * Class implementation of the `RatioElement` interface.
  *
  * @remarks
- * Aspect ratio representation (e.g. "16:9", "4:3", "1:1").
+ * Displays a numeric aspect ratio as a ratio expression. Provide a positive value meaningful to the surrounding content; this type does not encode the source image dimensions.
  */
 export declare class RatioElementClass extends BaseUiElement<RatioElement> implements RatioElement {
     /**
@@ -1007,7 +1788,12 @@ export declare class RatioElementClass extends BaseUiElement<RatioElement> imple
      * @defaultValue "ratio"
      */
     readonly type = "ratio";
-    /** Aspect ratio numerical expression */
+    /**
+     * Aspect ratio numerical expression
+     *
+     * @remarks
+     * Numeric ratio value used by the renderer to produce an aspect-ratio display.
+     */
     readonly value: number;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     readonly modifiers?: PrimitiveModifiers;
@@ -1015,17 +1801,63 @@ export declare class RatioElementClass extends BaseUiElement<RatioElement> imple
      * Constructs a new `RatioElementClass` instance.
      *
      * @param value - Aspect ratio numerical expression
+  
+    Numeric ratio value used by the renderer to produce an aspect-ratio display.
      * @param options - Optional component settings. (modifiers).
      */
     constructor(value: number, options?: {
         modifiers?: PrimitiveModifiers;
     });
 }
+/**
+ * Class implementation of the `DimensionsElement` interface.
+ *
+ * @remarks
+ * Displays a width/height pair as image dimensions. Both values are positive pixel counts; together they describe dimensions, not an aspect ratio or a resize request.
+ */
+export declare class DimensionsElementClass extends BaseUiElement<DimensionsElement> implements DimensionsElement {
+    /**
+     * Discriminator identifier for `DimensionsElement`.
+     *
+     * @defaultValue "dimensions"
+     */
+    readonly type = "dimensions";
+    /**
+     * Width in pixels
+     *
+     * @remarks
+     * Horizontal pixel count. Values below one are rejected by the schema constraint.
+     */
+    readonly width: number;
+    /**
+     * Height in pixels
+     *
+     * @remarks
+     * Vertical pixel count. Values below one are rejected by the schema constraint.
+     */
+    readonly height: number;
+    /** Optional visual modifiers (copyable) */
+    readonly modifiers?: BaseModifiers;
+    /**
+     * Constructs a new `DimensionsElementClass` instance.
+     *
+     * @param width - Width in pixels
+  
+    Horizontal pixel count. Values below one are rejected by the schema constraint.
+     * @param height - Height in pixels
+  
+    Vertical pixel count. Values below one are rejected by the schema constraint.
+     * @param options - Optional component settings. (modifiers).
+     */
+    constructor(width: number, height: number, options?: {
+        modifiers?: BaseModifiers;
+    });
+}
 /**
  * Class implementation of the `ColourElement` interface.
  *
  * @remarks
- * Single color representation with hex value, shape/size styling, text display toggle, and copy affordance.
+ * Displays one color swatch with configurable geometry and optional adjacent text. Supply the color as a hexadecimal string; the schema leaves exact accepted hex formats to the renderer.
  */
 export declare class ColourElementClass extends BaseUiElement<ColourElement> implements ColourElement {
     /**
@@ -1034,25 +1866,44 @@ export declare class ColourElementClass extends BaseUiElement<ColourElement> imp
      * @defaultValue "color"
      */
     readonly type = "color";
-    /** Hexadecimal color code */
+    /**
+     * Hexadecimal color code
+     *
+     * @remarks
+     * Color value used to draw the swatch. Use a hexadecimal representation supported by the client renderer.
+     */
     readonly value: string;
-    /** Optional descriptive color name label */
+    /**
+     * Optional descriptive color name label
+     *
+     * @remarks
+     * Human-readable color name available to the renderer when text is shown.
+     */
     readonly label?: string;
     /**
      * Whether to display the textual color code or label next to the swatch
      *
+     * @remarks
+     * When true, allows the renderer to show the color's text label alongside the swatch. The default is true.
+     *
      * @defaultValue true
      */
     readonly showText?: boolean;
     /**
      * Visual shape of the color indicator
      *
+     * @remarks
+     * Geometry used for the swatch; defaults to a circle.
+     *
      * @defaultValue Shape.circle
      */
     readonly shape?: Shape;
     /**
      * Visual size of the color indicator
      *
+     * @remarks
+     * Relative size class for the swatch; defaults to medium.
+     *
      * @defaultValue Size.medium
      */
     readonly size?: Size;
@@ -1062,6 +1913,8 @@ export declare class ColourElementClass extends BaseUiElement<ColourElement> imp
      * Constructs a new `ColourElementClass` instance.
      *
      * @param value - Hexadecimal color code
+  
+    Color value used to draw the swatch. Use a hexadecimal representation supported by the client renderer.
      * @param options - Optional component settings. (label, showText (defaults to `true`), shape (defaults to `circle`), size (defaults to `medium`), modifiers).
      */
     constructor(value: string, options?: {
@@ -1076,7 +1929,7 @@ export declare class ColourElementClass extends BaseUiElement<ColourElement> imp
  * Class implementation of the `NumberUnboundedElement` interface.
  *
  * @remarks
- * Plain unbounded numeric value primitive element.
+ * Displays a numeric value without a progress scale or rating interpretation. Use unit to communicate the measurement context; no range is imposed by this model.
  */
 export declare class NumberUnboundedElementClass extends BaseUiElement<NumberUnboundedElement> implements NumberUnboundedElement {
     /**
@@ -1085,9 +1938,19 @@ export declare class NumberUnboundedElementClass extends BaseUiElement<NumberUnb
      * @defaultValue "number-unbounded"
      */
     readonly type = "number-unbounded";
-    /** Numeric value */
+    /**
+     * Numeric value
+     *
+     * @remarks
+     * Number to display. Its meaning and any valid range are defined by the producing feature.
+     */
     readonly value: number;
-    /** Optional unit suffix (e.g. "px", "ms", "MB") */
+    /**
+     * Optional unit suffix (e.g. "px", "ms", "MB")
+     *
+     * @remarks
+     * Short unit label appended or otherwise associated with the displayed value. Include only the unit text, not a second copy of the number.
+     */
     readonly unit?: string;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     readonly modifiers?: PrimitiveModifiers;
@@ -1095,6 +1958,8 @@ export declare class NumberUnboundedElementClass extends BaseUiElement<NumberUnb
      * Constructs a new `NumberUnboundedElementClass` instance.
      *
      * @param value - Numeric value
+  
+    Number to display. Its meaning and any valid range are defined by the producing feature.
      * @param options - Optional component settings. (unit, modifiers).
      */
     constructor(value: number, options?: {
@@ -1106,7 +1971,7 @@ export declare class NumberUnboundedElementClass extends BaseUiElement<NumberUnb
  * Class implementation of the `NumberBoundedStarsElement` interface.
  *
  * @remarks
- * Bounded numeric rating represented as visual stars.
+ * Displays a score on a star scale. Keep value within the scale from zero through maximum; this model declares the scale metadata but does not impose a numeric validation bound.
  */
 export declare class NumberBoundedStarsElementClass extends BaseUiElement<NumberBoundedStarsElement> implements NumberBoundedStarsElement {
     /**
@@ -1115,9 +1980,19 @@ export declare class NumberBoundedStarsElementClass extends BaseUiElement<Number
      * @defaultValue "number-stars"
      */
     readonly type = "number-stars";
-    /** Numeric rating score */
+    /**
+     * Numeric rating score
+     *
+     * @remarks
+     * Score represented by the filled portion of the star display.
+     */
     readonly value: number;
-    /** Maximum rating scale (defaults to 5) */
+    /**
+     * Maximum rating scale (defaults to 5)
+     *
+     * @remarks
+     * Upper end of the rating scale. When omitted, the scale is five; value should use the same scale.
+     */
     readonly maximum?: number;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     readonly modifiers?: PrimitiveModifiers;
@@ -1125,6 +2000,8 @@ export declare class NumberBoundedStarsElementClass extends BaseUiElement<Number
      * Constructs a new `NumberBoundedStarsElementClass` instance.
      *
      * @param value - Numeric rating score
+  
+    Score represented by the filled portion of the star display.
      * @param options - Optional component settings. (maximum, modifiers).
      */
     constructor(value: number, options?: {
@@ -1136,7 +2013,7 @@ export declare class NumberBoundedStarsElementClass extends BaseUiElement<Number
  * Class implementation of the `NumberBoundedMeterElement` interface.
  *
  * @remarks
- * Bounded numeric meter representation (read-only progress / score bar).
+ * Displays a scalar value against a minimum-to-maximum range. Supply comparable bounds and a value in that range; optional label and unit customize the textual readout without changing the meter scale.
  */
 export declare class NumberBoundedMeterElementClass extends BaseUiElement<NumberBoundedMeterElement> implements NumberBoundedMeterElement {
     /**
@@ -1145,15 +2022,40 @@ export declare class NumberBoundedMeterElementClass extends BaseUiElement<Number
      * @defaultValue "number-meter"
      */
     readonly type = "number-meter";
-    /** Numeric value */
+    /**
+     * Numeric value
+     *
+     * @remarks
+     * Current measurement or score represented by the meter.
+     */
     readonly value: number;
-    /** Minimum scale bound (defaults to 0) */
+    /**
+     * Minimum scale bound (defaults to 0)
+     *
+     * @remarks
+     * Lower end of the meter range. Defaults to zero when omitted.
+     */
     readonly minimum?: number;
-    /** Maximum scale bound (e.g. 100) */
+    /**
+     * Maximum scale bound (e.g. 100)
+     *
+     * @remarks
+     * Upper end of the meter range. Choose a bound consistent with value and minimum.
+     */
     readonly maximum?: number;
-    /** Optional custom text label override (e.g. "68 / 100") */
+    /**
+     * Optional custom text label override (e.g. "68 / 100")
+     *
+     * @remarks
+     * Optional readout text to use instead of a renderer-generated value and range label.
+     */
     readonly label?: string;
-    /** Optional unit suffix (e.g. "%") */
+    /**
+     * Optional unit suffix (e.g. "%")
+     *
+     * @remarks
+     * Unit associated with the value, such as a percent sign. This affects display only and does not convert the numeric value.
+     */
     readonly unit?: string;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     readonly modifiers?: PrimitiveModifiers;
@@ -1161,6 +2063,8 @@ export declare class NumberBoundedMeterElementClass extends BaseUiElement<Number
      * Constructs a new `NumberBoundedMeterElementClass` instance.
      *
      * @param value - Numeric value
+  
+    Current measurement or score represented by the meter.
      * @param options - Optional component settings. (minimum, maximum, label, unit, modifiers).
      */
     constructor(value: number, options?: {
@@ -1172,61 +2076,57 @@ export declare class NumberBoundedMeterElementClass extends BaseUiElement<Number
     });
 }
 /**
- * Class implementation of the `BooleanPlainElement` interface.
+ * Class implementation of the `BooleanElement` interface.
  *
  * @remarks
- * Plain boolean value representation (textual "true" / "false").
+ * Displays a boolean state using text or a badge. The representation determines whether true/false labels or a colored badge are used; configured labels and variant are presentation choices only.
  */
-export declare class BooleanPlainElementClass extends BaseUiElement<BooleanPlainElement> implements BooleanPlainElement {
+export declare class BooleanElementClass extends BaseUiElement<BooleanElement> implements BooleanElement {
     /**
-     * Discriminator identifier for `BooleanPlainElement`.
+     * Discriminator identifier for `BooleanElement`.
      *
-     * @defaultValue "boolean-plain"
+     * @defaultValue "boolean"
      */
-    readonly type = "boolean-plain";
-    /** Boolean state value */
-    readonly value: boolean;
-    /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
-    readonly modifiers?: PrimitiveModifiers;
+    readonly type = "boolean";
     /**
-     * Constructs a new `BooleanPlainElementClass` instance.
+     * Boolean state value
      *
-     * @param value - Boolean state value
-     * @param options - Optional component settings. (modifiers).
+     * @remarks
+     * State to display. This remains a boolean value in the data model even when the renderer substitutes custom labels.
      */
-    constructor(value: boolean, options?: {
-        modifiers?: PrimitiveModifiers;
-    });
-}
-/**
- * Class implementation of the `BooleanBadgeElement` interface.
- *
- * @remarks
- * Visual badge pill representation of a boolean state.
- */
-export declare class BooleanBadgeElementClass extends BaseUiElement<BooleanBadgeElement> implements BooleanBadgeElement {
+    readonly value: boolean;
     /**
-     * Discriminator identifier for `BooleanBadgeElement`.
+     * Display representation mode
      *
-     * @defaultValue "boolean-badge"
+     * @remarks
+     * Selects ordinary text or a badge pill. Badge color applies only to badge presentation.
+     *
+     * @defaultValue BooleanRepresentation.plain
      */
-    readonly type = "boolean-badge";
-    /** Boolean state value */
-    readonly value: boolean;
+    readonly representation?: BooleanRepresentation;
     /**
      * Custom display label when true (defaults to "true")
      *
+     * @remarks
+     * Text used for the true state in plain representation. Defaults to the literal text true.
+     *
      * @defaultValue "true"
      */
     readonly trueLabel?: string;
     /**
      * Custom display label when false (defaults to "false")
      *
+     * @remarks
+     * Text used for the false state in plain representation. Defaults to the literal text false.
+     *
      * @defaultValue "false"
      */
     readonly falseLabel?: string;
     /**
-     * Badge color tone
+     * Badge color tone when rendered as badge
+     *
+     * @remarks
+     * Semantic color treatment for badge presentation; it has no effect in plain representation.
      *
      * @defaultValue BadgeVariant.neutral
      */
@@ -1234,12 +2134,15 @@ export declare class BooleanBadgeElementClass extends BaseUiElement<BooleanBadge
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     readonly modifiers?: PrimitiveModifiers;
     /**
-     * Constructs a new `BooleanBadgeElementClass` instance.
+     * Constructs a new `BooleanElementClass` instance.
      *
      * @param value - Boolean state value
-     * @param options - Optional component settings. (trueLabel (defaults to `true`), falseLabel (defaults to `false`), variant (defaults to `neutral`), modifiers).
+  
+    State to display. This remains a boolean value in the data model even when the renderer substitutes custom labels.
+     * @param options - Optional component settings. (representation (defaults to `plain`), trueLabel (defaults to `true`), falseLabel (defaults to `false`), variant (defaults to `neutral`), modifiers).
      */
     constructor(value: boolean, options?: {
+        representation?: BooleanRepresentation;
         trueLabel?: string;
         falseLabel?: string;
         variant?: BadgeVariant;
@@ -1250,7 +2153,7 @@ export declare class BooleanBadgeElementClass extends BaseUiElement<BooleanBadge
  * Class implementation of the `TimestampElement` interface.
  *
  * @remarks
- * Formatted date and time representation.
+ * Displays an epoch timestamp using a selected date/time format. The input is a count of milliseconds, not seconds; relative formatting is interpreted by the consumer.
  */
 export declare class TimestampElementClass extends BaseUiElement<TimestampElement> implements TimestampElement {
     /**
@@ -1259,11 +2162,19 @@ export declare class TimestampElementClass extends BaseUiElement<TimestampElemen
      * @defaultValue "timestamp"
      */
     readonly type = "timestamp";
-    /** The timestamp in milliseconds */
+    /**
+     * The timestamp in milliseconds
+     *
+     * @remarks
+     * Unix epoch timestamp measured in milliseconds. Convert seconds-based timestamps before assigning this value.
+     */
     readonly value: number;
     /**
      * Presentation date/time format
      *
+     * @remarks
+     * Controls whether the timestamp is shown as date and time, date only, time only, or relative text. The default is datetime.
+     *
      * @defaultValue TimestampFormat.datetime
      */
     readonly format?: TimestampFormat;
@@ -1273,6 +2184,8 @@ export declare class TimestampElementClass extends BaseUiElement<TimestampElemen
      * Constructs a new `TimestampElementClass` instance.
      *
      * @param value - The timestamp in milliseconds
+  
+    Unix epoch timestamp measured in milliseconds. Convert seconds-based timestamps before assigning this value.
      * @param options - Optional component settings. (format (defaults to `datetime`), modifiers).
      */
     constructor(value: number, options?: {
@@ -1284,7 +2197,7 @@ export declare class TimestampElementClass extends BaseUiElement<TimestampElemen
  * Class implementation of the `ImageReferenceElement` interface.
  *
  * @remarks
- * Thumbnail image reference with placeholder fallback handling.
+ * References an image source for thumbnail rendering and provides accessible text and a fallback source. The client determines loading, sizing, and placeholder behavior.
  */
 export declare class ImageReferenceElementClass extends BaseUiElement<ImageReferenceElement> implements ImageReferenceElement {
     /**
@@ -1293,22 +2206,42 @@ export declare class ImageReferenceElementClass extends BaseUiElement<ImageRefer
      * @defaultValue "image-ref"
      */
     readonly type = "image-ref";
-    /** Image source URI (HTTPS URL, base64 data URI, or asset path) */
+    /**
+     * Image source URI (HTTPS URL, base64 data URI, or asset path)
+     *
+     * @remarks
+     * Source URI understood by the client renderer. Supported forms include HTTPS locations, base64 data URIs, and client asset paths; this field is not raw image bytes.
+     */
     readonly src: string;
-    /** Accessible alternative description */
+    /**
+     * Accessible alternative description
+     *
+     * @remarks
+     * Alternative text describing the image for assistive technology. Provide meaningful text when the image conveys information; omit it only when it is decorative.
+     */
     readonly alt?: string;
     /**
      * Aspect ratio of the thumbnail container
      *
+     * @remarks
+     * Preferred ratio of the rendered thumbnail container, expressed as a ratio string such as 1:1. It controls presentation rather than modifying the source image.
+     *
      * @defaultValue "1:1"
      */
     readonly aspectRatio?: string;
-    /** Fallback placeholder image URI */
+    /**
+     * Fallback placeholder image URI
+     *
+     * @remarks
+     * Optional source to display when the primary image cannot be loaded. It follows the same URI conventions as src.
+     */
     readonly placeholder?: string;
     /**
      * Constructs a new `ImageReferenceElementClass` instance.
      *
      * @param src - Image source URI (HTTPS URL, base64 data URI, or asset path)
+  
+    Source URI understood by the client renderer. Supported forms include HTTPS locations, base64 data URIs, and client asset paths; this field is not raw image bytes.
      * @param options - Optional component settings. (alt, aspectRatio (defaults to `1:1`), placeholder).
      */
     constructor(src: string, options?: {
@@ -1321,7 +2254,7 @@ export declare class ImageReferenceElementClass extends BaseUiElement<ImageRefer
  * Class implementation of the `ButtonActionElement` interface.
  *
  * @remarks
- * Interactive button action triggering an extension command.
+ * When activated, the client dispatches commandId to the specified extension and may include target and parameters as command input. disabled and variant affect presentation and availability, not the command's authorization.
  */
 export declare class ButtonActionElementClass extends BaseUiAction<ButtonActionElement> implements ButtonActionElement {
     /**
@@ -1330,25 +2263,56 @@ export declare class ButtonActionElementClass extends BaseUiAction<ButtonActionE
      * @defaultValue "button"
      */
     readonly type = "button";
-    /** Command identifier to invoke */
+    /**
+     * Command identifier to invoke
+     *
+     * @remarks
+     * Identifier of the registered extension command to dispatch when the button is activated.
+     */
     readonly commandId: string;
-    /** Display label for the action */
+    /**
+     * Display label for the action
+     *
+     * @remarks
+     * User-facing label shown on the control. Keep it short and action-oriented.
+     */
     readonly label: string;
-    /** Extension identifier owning the target command */
+    /**
+     * Extension identifier owning the target command
+     *
+     * @remarks
+     * Extension that registers commandId. Omit only when the client can resolve the command in the current extension context.
+     */
     readonly extensionId?: string;
-    /** Target entity or context identifier */
+    /**
+     * Target entity or context identifier
+     *
+     * @remarks
+     * Optional entity or context identifier forwarded to the command handler. Its format is determined by the target extension.
+     */
     readonly target?: string;
-    /** Optional arbitrary parameters payload forwarded to the command handler */
+    /**
+     * Optional arbitrary parameters payload forwarded to the command handler
+     *
+     * @remarks
+     * JSON-compatible arguments passed to the extension command. Define and validate their shape in the command implementation.
+     */
     readonly parameters?: Record<string, unknown>;
     /**
      * Whether the button is disabled / unavailable
      *
+     * @remarks
+     * When true, the client renders the action as unavailable and should not dispatch it from user activation.
+     *
      * @defaultValue false
      */
     readonly disabled?: boolean;
     /**
      * Button visual style variant
      *
+     * @remarks
+     * Selects the button's emphasis style. Use danger for destructive operations and primary for the main recommended action; the variant does not change behavior.
+     *
      * @defaultValue ButtonVariant.secondary
      */
     readonly variant?: ButtonVariant;
@@ -1356,7 +2320,11 @@ export declare class ButtonActionElementClass extends BaseUiAction<ButtonActionE
      * Constructs a new `ButtonActionElementClass` instance.
      *
      * @param commandId - Command identifier to invoke
+  
+    Identifier of the registered extension command to dispatch when the button is activated.
      * @param label - Display label for the action
+  
+    User-facing label shown on the control. Keep it short and action-oriented.
      * @param options - Optional component settings. (extensionId, target, parameters, disabled (defaults to `false`), variant (defaults to `secondary`)).
      */
     constructor(commandId: string, label: string, options?: {
@@ -1371,24 +2339,38 @@ export declare class ButtonActionElementClass extends BaseUiAction<ButtonActionE
  * Class implementation of the `ExternalLinkActionElement` interface.
  *
  * @remarks
- * External link action distinct from inline URL text values.
+ * Renders a user-invokable action that opens a destination externally. Use StringUrlElement for a link embedded in content rather than an action control.
  */
 export declare class ExternalLinkActionElementClass extends BaseUiAction<ExternalLinkActionElement> implements ExternalLinkActionElement {
     /**
-     * Discriminator identifier for `ExternalLinkActionElement`.
+     * Discriminator identifier for `ExternalLinkActionElement`.
+     *
+     * @defaultValue "external-link"
+     */
+    readonly type = "external-link";
+    /**
+     * Target URL destination
+     *
+     * @remarks
+     * External destination opened when the user activates the link action. The client controls how external navigation is handed to the platform.
+     */
+    readonly url: string;
+    /**
+     * Display label for the action
      *
-     * @defaultValue "external-link"
+     * @remarks
+     * User-facing label shown on the control. Keep it short and action-oriented.
      */
-    readonly type = "external-link";
-    /** Target URL destination */
-    readonly url: string;
-    /** Display label for the action */
     readonly label: string;
     /**
      * Constructs a new `ExternalLinkActionElementClass` instance.
      *
      * @param url - Target URL destination
+  
+    External destination opened when the user activates the link action. The client controls how external navigation is handed to the platform.
      * @param label - Display label for the action
+  
+    User-facing label shown on the control. Keep it short and action-oriented.
      */
     constructor(url: string, label: string);
 }
@@ -1396,7 +2378,7 @@ export declare class ExternalLinkActionElementClass extends BaseUiAction<Externa
  * Class implementation of the `MarkdownBlockElement` interface.
  *
  * @remarks
- * Full Markdown fallback block rendered with core typographic hierarchy, spacing, and styling.
+ * Use this custom-renderer escape hatch when the structured ViewKit elements cannot express the required rich text. Markdown rendering is a presentation fallback; prefer typed elements when consumers need to inspect individual values.
  */
 export declare class MarkdownBlockElementClass extends BaseUiElement<MarkdownBlockElement> implements MarkdownBlockElement {
     /**
@@ -1405,7 +2387,12 @@ export declare class MarkdownBlockElementClass extends BaseUiElement<MarkdownBlo
      * @defaultValue "markdown"
      */
     readonly type = "markdown";
-    /** Raw Markdown markup content */
+    /**
+     * Raw Markdown markup content
+     *
+     * @remarks
+     * Markdown source consumed by the client renderer. The schema treats it as an opaque string and does not validate the markup or its links.
+     */
     readonly content: string;
     /** Optional visual modifiers (copyable) */
     readonly modifiers?: BaseModifiers;
@@ -1413,6 +2400,8 @@ export declare class MarkdownBlockElementClass extends BaseUiElement<MarkdownBlo
      * Constructs a new `MarkdownBlockElementClass` instance.
      *
      * @param content - Raw Markdown markup content
+  
+    Markdown source consumed by the client renderer. The schema treats it as an opaque string and does not validate the markup or its links.
      * @param options - Optional component settings. (modifiers).
      */
     constructor(content: string, options?: {
@@ -1423,7 +2412,7 @@ export declare class MarkdownBlockElementClass extends BaseUiElement<MarkdownBlo
  * Class implementation of the `HtmlBlockElement` interface.
  *
  * @remarks
- * Sandboxed HTML rendering escape hatch.
+ * Use only when structured elements or Markdown cannot represent the required content. Rendering occurs in a sandboxed host context, but callers should still avoid embedding untrusted content and should not assume access to application privileges.
  */
 export declare class HtmlBlockElementClass extends BaseUiElement<HtmlBlockElement> implements HtmlBlockElement {
     /**
@@ -1432,7 +2421,12 @@ export declare class HtmlBlockElementClass extends BaseUiElement<HtmlBlockElemen
      * @defaultValue "html"
      */
     readonly type = "html";
-    /** Raw HTML markup content */
+    /**
+     * Raw HTML markup content
+     *
+     * @remarks
+     * HTML source passed to the custom renderer. This is an opaque string, not a typed or sanitized DOM structure.
+     */
     readonly content: string;
     /** Optional visual modifiers (copyable) */
     readonly modifiers?: BaseModifiers;
@@ -1440,6 +2434,8 @@ export declare class HtmlBlockElementClass extends BaseUiElement<HtmlBlockElemen
      * Constructs a new `HtmlBlockElementClass` instance.
      *
      * @param content - Raw HTML markup content
+  
+    HTML source passed to the custom renderer. This is an opaque string, not a typed or sanitized DOM structure.
      * @param options - Optional component settings. (modifiers).
      */
     constructor(content: string, options?: {
@@ -1450,32 +2446,48 @@ export declare class HtmlBlockElementClass extends BaseUiElement<HtmlBlockElemen
  * Class implementation of the `Slot` interface.
  *
  * @remarks
- * Single slot within a multi-slot horizontal row layout.
+ * A slot combines an optional label, a relative width, and one visual child. Slot widths are percentages of the row and should be chosen so the full row's widths form a usable layout.
  */
 export declare class SlotClass extends ViewKitNode<Slot> implements Slot {
-    /** Rendered content inside the slot */
+    /**
+     * Rendered content inside the slot
+     *
+     * @remarks
+     * One visual element displayed in this slot. Use a nested layout element when the slot itself needs multiple children.
+     */
     readonly content: UiElement;
-    /** Optional slot label (e.g. "Slot A") */
+    /**
+     * Optional slot label (e.g. "Slot A")
+     *
+     * @remarks
+     * Short text identifying this region of the row. It is independent of the rendered content.
+     */
     readonly label?: string;
-    /** Relative or fractional width proportion (e.g. "1/3", "2/3", "100px", "auto") */
-    readonly width?: string;
+    /**
+     * Width percentage (1-100)
+     *
+     * @remarks
+     * Relative share of the row width. The schema constrains explicit values to the inclusive range 1 through 100.
+     */
+    readonly width?: number;
     /**
      * Constructs a new `SlotClass` instance.
      *
      * @param content - Rendered content inside the slot
+  
+    One visual element displayed in this slot. Use a nested layout element when the slot itself needs multiple children.
      * @param options - Optional component settings. (label, width).
      */
     constructor(content: UiElement, options?: {
         label?: string;
-        width?: string;
+        width?: number;
     });
 }
 /**
  * Class implementation of the `MultiSlotElement` interface.
  *
  * @remarks
- * Multi-slot horizontal row with declared column width proportions.
- * Examples: "1/3 + 2/3", "equal thirds", "1/4 + 3/4".
+ * Use this layout when a row needs explicit regions with independently controlled widths. Each slot contains one child element; unlike FlowingElement, the layout does not automatically wrap a sequence of children.
  */
 export declare class MultiSlotElementClass extends BaseUiElement<MultiSlotElement> implements MultiSlotElement {
     /**
@@ -1484,26 +2496,27 @@ export declare class MultiSlotElementClass extends BaseUiElement<MultiSlotElemen
      * @defaultValue "multi-slot"
      */
     readonly type = "multi-slot";
-    /** List of slots comprising the row */
+    /**
+     * List of slots comprising the row
+     *
+     * @remarks
+     * Ordered slots in the row. Each slot's width is a percentage; arrange slot definitions in the intended visual order.
+     */
     readonly slots: Slot[];
-    /** Proportions descriptor (e.g. "1/3 + 2/3", "equal", "1/4 + 3/4") */
-    readonly proportions?: string;
     /**
      * Constructs a new `MultiSlotElementClass` instance.
      *
      * @param slots - List of slots comprising the row
-     * @param options - Optional component settings. (proportions).
+  
+    Ordered slots in the row. Each slot's width is a percentage; arrange slot definitions in the intended visual order.
      */
-    constructor(slots: Slot[], options?: {
-        proportions?: string;
-    });
+    constructor(slots: Slot[]);
 }
 /**
  * Class implementation of the `FlowingElement` interface.
  *
  * @remarks
- * Flowing inline layout container with automatic line wrapping.
- * Renders child elements horizontally in sequence, automatically wrapping to the next line when space runs out.
+ * Use for compact related values that should flow horizontally and wrap naturally at the available width. Child order is preserved; an optional separator is placed between neighboring children.
  */
 export declare class FlowingElementClass extends BaseUiElement<FlowingElement> implements FlowingElement {
     /**
@@ -1512,21 +2525,37 @@ export declare class FlowingElementClass extends BaseUiElement<FlowingElement> i
      * @defaultValue "flowing"
      */
     readonly type = "flowing";
-    /** List of child elements rendered sequentially with line wrapping */
+    /**
+     * List of child elements rendered sequentially with line wrapping
+     *
+     * @remarks
+     * Ordered children rendered in the flow. The client wraps them as needed rather than requiring callers to calculate line breaks.
+     */
     readonly elements: UiElement[];
+    /**
+     * Optional visual separator rendered between sequential child elements
+     *
+     * @remarks
+     * Separator placed between adjacent elements. Omit it when spacing or the child renderers already provide sufficient separation.
+     */
+    readonly separator?: Separator;
     /**
      * Constructs a new `FlowingElementClass` instance.
      *
      * @param elements - List of child elements rendered sequentially with line wrapping
+  
+    Ordered children rendered in the flow. The client wraps them as needed rather than requiring callers to calculate line breaks.
+     * @param options - Optional component settings. (separator).
      */
-    constructor(elements: UiElement[]);
+    constructor(elements: UiElement[], options?: {
+        separator?: Separator;
+    });
 }
 /**
  * Class implementation of the `LabelValueElement` interface.
  *
  * @remarks
- * Standard label and value row.
- * Displays a muted label on the left and value representation on the right with a vertical dividing line.
+ * Represents one named value with a muted left-hand label and a right-hand visual element. Use it for a single field; use TableElement for repeated rows or column-aligned data.
  */
 export declare class LabelValueElementClass extends BaseUiElement<LabelValueElement> implements LabelValueElement {
     /**
@@ -1535,13 +2564,26 @@ export declare class LabelValueElementClass extends BaseUiElement<LabelValueElem
      * @defaultValue "label-value"
      */
     readonly type = "label-value";
-    /** Key or descriptive label displayed muted on the left */
+    /**
+     * Key or descriptive label displayed muted on the left
+     *
+     * @remarks
+     * Human-readable name for the value. This text is rendered as the row label rather than as a separate UiElement.
+     */
     readonly label: string;
-    /** Rendered value element on the right */
+    /**
+     * Rendered value element on the right
+     *
+     * @remarks
+     * Value content rendered in the right-hand region. It may be a primitive or a nested structural element.
+     */
     readonly value: UiElement;
     /**
      * Whether to render a bottom border/hairline divider
      *
+     * @remarks
+     * Enables a horizontal separator beneath this row when true. Defaults to false.
+     *
      * @defaultValue false
      */
     readonly withDivider?: boolean;
@@ -1549,7 +2591,11 @@ export declare class LabelValueElementClass extends BaseUiElement<LabelValueElem
      * Constructs a new `LabelValueElementClass` instance.
      *
      * @param label - Key or descriptive label displayed muted on the left
+  
+    Human-readable name for the value. This text is rendered as the row label rather than as a separate UiElement.
      * @param value - Rendered value element on the right
+  
+    Value content rendered in the right-hand region. It may be a primitive or a nested structural element.
      * @param options - Optional component settings. (withDivider (defaults to `false`)).
      */
     constructor(label: string, value: UiElement, options?: {
@@ -1560,43 +2606,73 @@ export declare class LabelValueElementClass extends BaseUiElement<LabelValueElem
  * Class implementation of the `TableColumn` interface.
  *
  * @remarks
- * Column definition for structured tables.
+ * Describes one table column and its visual sizing. When columns are supplied, their order corresponds to the position of each cell in a row.
  */
 export declare class TableColumnClass extends ViewKitNode<TableColumn> implements TableColumn {
-    /** Display header text */
+    /**
+     * Display header text
+     *
+     * @remarks
+     * Optional header shown above values in this column. Omit when the table has no header row.
+     */
     readonly header?: string;
     /**
      * Text horizontal alignment
      *
+     * @remarks
+     * Horizontal alignment applied to cell content in the column. Defaults to left.
+     *
      * @defaultValue TableColumnAlign.left
      */
     readonly align?: TableColumnAlign;
-    /** Optional width constraint */
-    readonly width?: string;
+    /**
+     * Width percentage (1-100)
+     *
+     * @remarks
+     * Column width percentage used with widthMode. Explicit values are constrained to 1 through 100.
+     */
+    readonly width?: number;
+    /**
+     * Sizing mode for the provided width
+     *
+     * @remarks
+     * Determines whether width is a fixed percentage allocation or an upper bound. Defaults to fixed.
+     *
+     * @defaultValue TableColumnWidthMode.fixed
+     */
+    readonly widthMode?: TableColumnWidthMode;
     /**
      * Constructs a new `TableColumnClass` instance.
      *
-     * @param options - Optional component settings. (header, align (defaults to `left`), width).
+     * @param options - Optional component settings. (header, align (defaults to `left`), width, widthMode (defaults to `fixed`)).
      */
     constructor(options?: {
         header?: string;
         align?: TableColumnAlign;
-        width?: string;
+        width?: number;
+        widthMode?: TableColumnWidthMode;
     });
 }
 /**
  * Class implementation of the `TableRow` interface.
  *
  * @remarks
- * Single table row containing an array of cell values.
+ * A row's cell array is positional: cell at each index corresponds to the column at that index. Keep row lengths aligned with the table's explicit column definitions when present.
  */
 export declare class TableRowClass extends ViewKitNode<TableRow> implements TableRow {
-    /** Array of cell values corresponding to table columns */
+    /**
+     * Array of cell values corresponding to table columns
+     *
+     * @remarks
+     * Ordered contents for this row. Each cell is a UiElement so values can use the same primitive and layout renderers as other ViewKit content.
+     */
     readonly cells: UiElement[];
     /**
      * Constructs a new `TableRowClass` instance.
      *
      * @param cells - Array of cell values corresponding to table columns
+  
+    Ordered contents for this row. Each cell is a UiElement so values can use the same primitive and layout renderers as other ViewKit content.
      */
     constructor(cells: UiElement[]);
 }
@@ -1604,8 +2680,7 @@ export declare class TableRowClass extends ViewKitNode<TableRow> implements Tabl
  * Class implementation of the `TableElement` interface.
  *
  * @remarks
- * Structured tabular data representation.
- * Supports header/borderless modes, 2-column key-value tables, and 3-column data tables.
+ * Use for data that benefits from aligned rows and columns, including key/value and multi-column tables. Supply rows in display order; explicit columns are optional, and divider/striping flags independently control visual separators and alternating backgrounds.
  */
 export declare class TableElementClass extends BaseUiElement<TableElement> implements TableElement {
     /**
@@ -1614,42 +2689,56 @@ export declare class TableElementClass extends BaseUiElement<TableElement> imple
      * @defaultValue "table"
      */
     readonly type = "table";
-    /** Tabular data rows */
-    readonly rows: TableRow[];
     /**
-     * Whether to render a column header row
+     * Tabular data rows
      *
-     * @defaultValue true
+     * @remarks
+     * Ordered table rows. Each row's cells correspond positionally to the declared columns.
      */
-    readonly hasHeader?: boolean;
+    readonly rows: TableRow[];
     /**
      * Whether to render alternating row background colors
      *
+     * @remarks
+     * Enables alternating backgrounds across successive rows to improve scanability. Defaults to false.
+     *
      * @defaultValue false
      */
     readonly isStriped?: boolean;
     /**
      * Whether to render vertical column separators
      *
+     * @remarks
+     * Adds vertical dividers between columns when true. Defaults to false.
+     *
      * @defaultValue false
      */
     readonly withColumnSeparators?: boolean;
     /**
      * Whether to render horizontal row separators
      *
+     * @remarks
+     * Adds horizontal dividers between rows when true. Defaults to false.
+     *
      * @defaultValue false
      */
     readonly withRowSeparators?: boolean;
-    /** Optional explicit column definitions */
+    /**
+     * Optional explicit column definitions
+     *
+     * @remarks
+     * Optional ordered column metadata defining headers, alignment, and width. When omitted, the renderer may infer a basic layout from row cells.
+     */
     readonly columns?: TableColumn[];
     /**
      * Constructs a new `TableElementClass` instance.
      *
      * @param rows - Tabular data rows
-     * @param options - Optional component settings. (hasHeader (defaults to `true`), isStriped (defaults to `false`), withColumnSeparators (defaults to `false`), withRowSeparators (defaults to `false`), columns).
+  
+    Ordered table rows. Each row's cells correspond positionally to the declared columns.
+     * @param options - Optional component settings. (isStriped (defaults to `false`), withColumnSeparators (defaults to `false`), withRowSeparators (defaults to `false`), columns).
      */
     constructor(rows: TableRow[], options?: {
-        hasHeader?: boolean;
         isStriped?: boolean;
         withColumnSeparators?: boolean;
         withRowSeparators?: boolean;
@@ -1660,19 +2749,36 @@ export declare class TableElementClass extends BaseUiElement<TableElement> imple
  * Class implementation of the `RepeatingGroupEntry` interface.
  *
  * @remarks
- * Single entry within a repeating group.
+ * A repeating entry carries a stable display label and either one primary value or a list of nested elements, depending on the shape needed by the feature.
  */
 export declare class RepeatingGroupEntryClass extends ViewKitNode<RepeatingGroupEntry> implements RepeatingGroupEntry {
-    /** Entry label */
+    /**
+     * Entry label
+     *
+     * @remarks
+     * Short label identifying this entry within the repeated group.
+     */
     readonly label: string;
-    /** Primary entry value or nested elements */
+    /**
+     * Primary entry value or nested elements
+     *
+     * @remarks
+     * Optional primary visual value for a compact entry. Use elements for a multi-part structured entry.
+     */
     readonly value?: UiElement;
-    /** Nested elements for structured entries */
+    /**
+     * Nested elements for structured entries
+     *
+     * @remarks
+     * Optional ordered content for entries that require more than one value element.
+     */
     readonly elements?: UiElement[];
     /**
      * Constructs a new `RepeatingGroupEntryClass` instance.
      *
      * @param label - Entry label
+  
+    Short label identifying this entry within the repeated group.
      * @param options - Optional component settings. (value, elements).
      */
     constructor(label: string, options?: {
@@ -1684,7 +2790,7 @@ export declare class RepeatingGroupEntryClass extends ViewKitNode<RepeatingGroup
  * Class implementation of the `RepeatingGroupElement` interface.
  *
  * @remarks
- * Repeating group container where entries share uniform structure and retain per-entry labels.
+ * Groups a sequence of labeled entries under one optional section title. Use it when records have the same general presentation but need their own labels.
  */
 export declare class RepeatingGroupElementClass extends BaseUiElement<RepeatingGroupElement> implements RepeatingGroupElement {
     /**
@@ -1693,14 +2799,26 @@ export declare class RepeatingGroupElementClass extends BaseUiElement<RepeatingG
      * @defaultValue "repeating-group"
      */
     readonly type = "repeating-group";
-    /** List of repeated entry records */
+    /**
+     * List of repeated entry records
+     *
+     * @remarks
+     * Entries in display order. Each entry supplies its own label and content.
+     */
     readonly entries: RepeatingGroupEntry[];
-    /** Optional section header for the group */
+    /**
+     * Optional section header for the group
+     *
+     * @remarks
+     * Heading displayed for the repeated section, separate from the labels of individual entries.
+     */
     readonly title?: string;
     /**
      * Constructs a new `RepeatingGroupElementClass` instance.
      *
      * @param entries - List of repeated entry records
+  
+    Entries in display order. Each entry supplies its own label and content.
      * @param options - Optional component settings. (title).
      */
     constructor(entries: RepeatingGroupEntry[], options?: {
@@ -1711,7 +2829,7 @@ export declare class RepeatingGroupElementClass extends BaseUiElement<RepeatingG
  * Class implementation of the `CollapsibleGroupElement` interface.
  *
  * @remarks
- * Collapsible disclosure container (accordion) with summary badge.
+ * Groups nested content behind a disclosure control. The title names the group, summary can provide a compact status indicator, and defaultExpanded controls only the initial state.
  */
 export declare class CollapsibleGroupElementClass extends BaseUiElement<CollapsibleGroupElement> implements CollapsibleGroupElement {
     /**
@@ -1720,15 +2838,33 @@ export declare class CollapsibleGroupElementClass extends BaseUiElement<Collapsi
      * @defaultValue "collapsible-group"
      */
     readonly type = "collapsible-group";
-    /** Group title (e.g. "Show specimen details") */
+    /**
+     * Group title (e.g. "Show specimen details")
+     *
+     * @remarks
+     * Text shown on the disclosure control. Use a concise action or section name that remains meaningful while the content is collapsed.
+     */
     readonly title: string;
-    /** Nested content elements revealed when expanded */
+    /**
+     * Nested content elements revealed when expanded
+     *
+     * @remarks
+     * Ordered child elements made visible by expanding the group.
+     */
     readonly elements: UiElement[];
-    /** Secondary summary indicator (e.g. "2 neutral values") */
+    /**
+     * Secondary summary indicator (e.g. "2 neutral values")
+     *
+     * @remarks
+     * Compact contextual text shown alongside the title while the group is collapsed or expanded. It does not replace the nested content.
+     */
     readonly summary?: string;
     /**
      * Whether the disclosure is open/expanded by default
      *
+     * @remarks
+     * Initial expanded state requested by the data. Defaults to false; subsequent interaction is managed by the client.
+     *
      * @defaultValue false
      */
     readonly defaultExpanded?: boolean;
@@ -1736,7 +2872,11 @@ export declare class CollapsibleGroupElementClass extends BaseUiElement<Collapsi
      * Constructs a new `CollapsibleGroupElementClass` instance.
      *
      * @param title - Group title (e.g. "Show specimen details")
+  
+    Text shown on the disclosure control. Use a concise action or section name that remains meaningful while the content is collapsed.
      * @param elements - Nested content elements revealed when expanded
+  
+    Ordered child elements made visible by expanding the group.
      * @param options - Optional component settings. (summary, defaultExpanded (defaults to `false`)).
      */
     constructor(title: string, elements: UiElement[], options?: {
@@ -1748,7 +2888,7 @@ export declare class CollapsibleGroupElementClass extends BaseUiElement<Collapsi
  * Class implementation of the `DividerElement` interface.
  *
  * @remarks
- * Visual hairline separator separating sections or element groups.
+ * A standalone visual separator for dividing adjacent sections or element groups. Use the divider flags on tables or rows when the separator is part of that structure.
  */
 export declare class DividerElementClass extends BaseUiElement<DividerElement> implements DividerElement {
     /**
@@ -1760,6 +2900,9 @@ export declare class DividerElementClass extends BaseUiElement<DividerElement> i
     /**
      * Line styling
      *
+     * @remarks
+     * Visual stroke treatment for the separator. Defaults to a subtle hairline.
+     *
      * @defaultValue DividerStyle.hairline
      */
     readonly style?: DividerStyle;
@@ -1776,12 +2919,15 @@ export declare class DividerElementClass extends BaseUiElement<DividerElement> i
  * Class implementation of the `Envelop` interface.
  *
  * @remarks
- * Base envelope container model holding the schema version attribute.
+ * All root ViewKit documents extend this envelope so consumers can identify the schema contract version before processing the root content.
  */
 export declare class EnvelopClass extends ViewKitNode<Envelop> implements Envelop {
     /**
      * Schema specification version
      *
+     * @remarks
+     * Version of the ViewKit envelope contract. It is a literal value and should be preserved when serializing or forwarding a document.
+     *
      * @defaultValue "1.0"
      */
     readonly schemaVersion: "1.0";
@@ -1798,14 +2944,22 @@ export declare class EnvelopClass extends ViewKitNode<Envelop> implements Envelo
  * Class implementation of the `UiContainer` interface.
  *
  * @remarks
- * Container model representing an ordered list of visual elements.
+ * Provides the shared root content collection inherited by cards and other root models. The order of elements is significant and is preserved by the renderer.
  */
 export declare class UiContainerClass extends ViewKitNode<UiContainer> implements UiContainer {
-    /** Ordered list of visual elements, structures, and content */
+    /**
+     * Ordered list of visual elements, structures, and content
+     *
+     * @remarks
+     * Top-level visual content in render order. Use a structural element to group related children and primitive elements for individual values.
+     */
     readonly elements: UiElement[];
     /**
      * Schema specification version
      *
+     * @remarks
+     * Version of the ViewKit envelope contract. It is a literal value and should be preserved when serializing or forwarding a document.
+     *
      * @defaultValue "1.0"
      */
     readonly schemaVersion: "1.0";
@@ -1813,6 +2967,8 @@ export declare class UiContainerClass extends ViewKitNode<UiContainer> implement
      * Constructs a new `UiContainerClass` instance.
      *
      * @param elements - Ordered list of visual elements, structures, and content
+  
+    Top-level visual content in render order. Use a structural element to group related children and primitive elements for individual values.
      * @param options - Optional component settings. (schemaVersion (defaults to `1.0`)).
      */
     constructor(elements: UiElement[], options?: {
@@ -1823,21 +2979,43 @@ export declare class UiContainerClass extends ViewKitNode<UiContainer> implement
  * Class implementation of the `UiCard` interface.
  *
  * @remarks
- * Root Card container model.
- * Represents a complete feature card rendered inside the 360px panel.
+ * A complete card has a required title and ordered content inherited from UiContainer. It is designed for the feature-card surface; description and actions supplement the content, with action controls rendered separately from the element list.
  */
 export declare class UiCardClass extends ViewKitNode<UiCard> implements UiCard {
-    /** Human-readable feature title displayed in the card header */
+    /**
+     * Human-readable feature title displayed in the card header
+     *
+     * @remarks
+     * Primary heading for the card. Keep it concise enough for the card header; longer explanatory text belongs in description or elements.
+     */
     readonly title: string;
-    /** Ordered list of visual elements, structures, and content */
+    /**
+     * Ordered list of visual elements, structures, and content
+     *
+     * @remarks
+     * Top-level visual content in render order. Use a structural element to group related children and primitive elements for individual values.
+     */
     readonly elements: UiElement[];
-    /** Optional neutral subtitle / description for the feature */
+    /**
+     * Optional neutral subtitle / description for the feature
+     *
+     * @remarks
+     * Brief secondary context shown with the title. Use the content elements for detailed information rather than placing an entire report in this field.
+     */
     readonly description?: string;
-    /** Optional card action buttons rendered at the base of the feature card */
+    /**
+     * Optional card action buttons rendered at the base of the feature card
+     *
+     * @remarks
+     * Optional user-invokable actions shown after the card content. Their order is preserved and each action's own fields define its command or link behavior.
+     */
     readonly actions?: UiAction[];
     /**
      * Schema specification version
      *
+     * @remarks
+     * Version of the ViewKit envelope contract. It is a literal value and should be preserved when serializing or forwarding a document.
+     *
      * @defaultValue "1.0"
      */
     readonly schemaVersion: "1.0";
@@ -1845,7 +3023,11 @@ export declare class UiCardClass extends ViewKitNode<UiCard> implements UiCard {
      * Constructs a new `UiCardClass` instance.
      *
      * @param title - Human-readable feature title displayed in the card header
+  
+    Primary heading for the card. Keep it concise enough for the card header; longer explanatory text belongs in description or elements.
      * @param elements - Ordered list of visual elements, structures, and content
+  
+    Top-level visual content in render order. Use a structural element to group related children and primitive elements for individual values.
      * @param options - Optional component settings. (description, actions, schemaVersion (defaults to `1.0`)).
      */
     constructor(title: string, elements: UiElement[], options?: {
@@ -1858,7 +3040,7 @@ export declare class UiCardClass extends ViewKitNode<UiCard> implements UiCard {
  * Fluent builder for constructing strongly-typed `UiContainer` instances.
  *
  * @remarks
- * Container model representing an ordered list of visual elements.
+ * Provides the shared root content collection inherited by cards and other root models. The order of elements is significant and is preserved by the renderer.
  */
 export declare class UiContainerBuilder {
     private readonly _elements;
@@ -1879,40 +3061,47 @@ export declare class UiContainerBuilder {
      */
     addElements(...items: UiElement[]): this;
     /**
-     * Appends a `StringShortElement` component.
+     * Appends a `StringElement` component.
      *
      * @remarks
-     * Short string primitive element.
-     * Supports plain text or compact chip pill presentation.
+     * Use this primitive for one textual value when a structured label/value row is unnecessary. Choose multiline for content whose line breaks should remain visible; modifiers apply presentation traits without changing the underlying value.
      *
      * @param value - Text value
+  
+    Text to render. Supply plain text; this field is not a Markdown or HTML document.
      * @param options - Optional component settings (representation (defaults to `plain`), modifiers).
      * @returns This builder instance for method chaining.
      */
-    addStringShort(value: string, options?: {
-        representation?: StringShortRepresentation;
+    addString(value: string, options?: {
+        representation?: StringRepresentation;
         modifiers?: PrimitiveModifiers;
     }): this;
     /**
-     * Appends a `StringLongElement` component.
+     * Appends a `StringsElement` component.
      *
      * @remarks
-     * Multiline text block primitive element for descriptions, comments, or prose.
+     * Use this primitive when several related strings should be rendered as one compact sequence. The client preserves the array order and inserts the selected separator between values.
      *
-     * @param value - Text value
-     * @param options - Optional component settings (modifiers).
+     * @param values - Array of string values
+  
+    Values to render in order. Each array entry remains a distinct item for chip presentation and is not parsed as a delimited string.
+     * @param options - Optional component settings (representation (defaults to `plain`), separator, modifiers).
      * @returns This builder instance for method chaining.
      */
-    addStringLong(value: string, options?: {
+    addStrings(values: string[], options?: {
+        representation?: StringRepresentation;
+        separator?: Separator;
         modifiers?: PrimitiveModifiers;
     }): this;
     /**
      * Appends a `StringCodeElement` component.
      *
      * @remarks
-     * Monospace code block or formatted code snippet representation.
+     * Use for source-like or preformatted textual content that should be rendered in a code-oriented style. The language is a presentation hint; the content is not parsed or validated as code by this contract.
      *
      * @param value - Text value
+  
+    Code or text snippet to display. Include any desired line breaks in this string.
      * @param options - Optional component settings (language, modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -1924,9 +3113,11 @@ export declare class UiContainerBuilder {
      * Appends a `XmlElement` component.
      *
      * @remarks
-     * XML markup code block element.
+     * Specialized code-oriented element for XML content. It uses the custom XML renderer rather than requiring consumers to construct a generic code block.
      *
      * @param value - XML content value
+  
+    XML markup to render. The contract carries the source text; it does not guarantee that the document is well-formed.
      * @param options - Optional component settings (modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -1937,9 +3128,11 @@ export declare class UiContainerBuilder {
      * Appends a `JsonElement` component.
      *
      * @remarks
-     * JSON data or structure representation element.
+     * Specialized representation for JSON text. Supply serialized JSON when consumers should display a JSON document; this field is a string and is not structurally validated here.
      *
      * @param value - JSON content value
+  
+    Serialized JSON text to render. No parsing or schema validation is implied by this element.
      * @param options - Optional component settings (modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -1950,9 +3143,11 @@ export declare class UiContainerBuilder {
      * Appends a `StringUrlElement` component.
      *
      * @remarks
-     * Hyperlink representation for external or internal URL navigation.
+     * Use this element when displayed text should also behave as a link. Unlike StringElement, the value is a navigation destination and may be paired with a separate human-readable label.
      *
      * @param value - Target URL or navigation destination
+  
+    Destination associated with the link. Supply a URL or client-recognized navigation target supported by the renderer.
      * @param options - Optional component settings (label, modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -1964,9 +3159,11 @@ export declare class UiContainerBuilder {
      * Appends a `IdentifierElement` component.
      *
      * @remarks
-     * Monospace semantic identifier representation.
+     * Use for identifiers, hashes, and other machine-oriented strings that benefit from monospace styling. The value remains text and is not resolved as a Picteus entity.
      *
      * @param value - Identifier string value
+  
+    Identifier text to display, such as an opaque ID or hash. Avoid embedding presentation markup in the value.
      * @param options - Optional component settings (modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -1977,22 +3174,44 @@ export declare class UiContainerBuilder {
      * Appends a `RatioElement` component.
      *
      * @remarks
-     * Aspect ratio representation (e.g. "16:9", "4:3", "1:1").
+     * Displays a numeric aspect ratio as a ratio expression. Provide a positive value meaningful to the surrounding content; this type does not encode the source image dimensions.
      *
      * @param value - Aspect ratio numerical expression
+  
+    Numeric ratio value used by the renderer to produce an aspect-ratio display.
      * @param options - Optional component settings (modifiers).
      * @returns This builder instance for method chaining.
      */
     addRatio(value: number, options?: {
         modifiers?: PrimitiveModifiers;
     }): this;
+    /**
+     * Appends a `DimensionsElement` component.
+     *
+     * @remarks
+     * Displays a width/height pair as image dimensions. Both values are positive pixel counts; together they describe dimensions, not an aspect ratio or a resize request.
+     *
+     * @param width - Width in pixels
+  
+    Horizontal pixel count. Values below one are rejected by the schema constraint.
+     * @param height - Height in pixels
+  
+    Vertical pixel count. Values below one are rejected by the schema constraint.
+     * @param options - Optional component settings (modifiers).
+     * @returns This builder instance for method chaining.
+     */
+    addDimensions(width: number, height: number, options?: {
+        modifiers?: BaseModifiers;
+    }): this;
     /**
      * Appends a `ColourElement` component.
      *
      * @remarks
-     * Single color representation with hex value, shape/size styling, text display toggle, and copy affordance.
+     * Displays one color swatch with configurable geometry and optional adjacent text. Supply the color as a hexadecimal string; the schema leaves exact accepted hex formats to the renderer.
      *
      * @param value - Hexadecimal color code
+  
+    Color value used to draw the swatch. Use a hexadecimal representation supported by the client renderer.
      * @param options - Optional component settings (label, showText (defaults to `true`), shape (defaults to `circle`), size (defaults to `medium`), modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2007,9 +3226,11 @@ export declare class UiContainerBuilder {
      * Appends a `ColourElement` component.
      *
      * @remarks
-     * Single color representation with hex value, shape/size styling, text display toggle, and copy affordance.
+     * Displays one color swatch with configurable geometry and optional adjacent text. Supply the color as a hexadecimal string; the schema leaves exact accepted hex formats to the renderer.
      *
      * @param value - Hexadecimal color code
+  
+    Color value used to draw the swatch. Use a hexadecimal representation supported by the client renderer.
      * @param options - Optional component settings (label, showText (defaults to `true`), shape (defaults to `circle`), size (defaults to `medium`), modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2024,9 +3245,11 @@ export declare class UiContainerBuilder {
      * Appends a `NumberUnboundedElement` component.
      *
      * @remarks
-     * Plain unbounded numeric value primitive element.
+     * Displays a numeric value without a progress scale or rating interpretation. Use unit to communicate the measurement context; no range is imposed by this model.
      *
      * @param value - Numeric value
+  
+    Number to display. Its meaning and any valid range are defined by the producing feature.
      * @param options - Optional component settings (unit, modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2038,9 +3261,11 @@ export declare class UiContainerBuilder {
      * Appends a `NumberBoundedStarsElement` component.
      *
      * @remarks
-     * Bounded numeric rating represented as visual stars.
+     * Displays a score on a star scale. Keep value within the scale from zero through maximum; this model declares the scale metadata but does not impose a numeric validation bound.
      *
      * @param value - Numeric rating score
+  
+    Score represented by the filled portion of the star display.
      * @param options - Optional component settings (maximum, modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2052,9 +3277,11 @@ export declare class UiContainerBuilder {
      * Appends a `NumberBoundedStarsElement` component.
      *
      * @remarks
-     * Bounded numeric rating represented as visual stars.
+     * Displays a score on a star scale. Keep value within the scale from zero through maximum; this model declares the scale metadata but does not impose a numeric validation bound.
      *
      * @param value - Numeric rating score
+  
+    Score represented by the filled portion of the star display.
      * @param options - Optional component settings (maximum, modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2066,9 +3293,11 @@ export declare class UiContainerBuilder {
      * Appends a `NumberBoundedMeterElement` component.
      *
      * @remarks
-     * Bounded numeric meter representation (read-only progress / score bar).
+     * Displays a scalar value against a minimum-to-maximum range. Supply comparable bounds and a value in that range; optional label and unit customize the textual readout without changing the meter scale.
      *
      * @param value - Numeric value
+  
+    Current measurement or score represented by the meter.
      * @param options - Optional component settings (minimum, maximum, label, unit, modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2083,9 +3312,11 @@ export declare class UiContainerBuilder {
      * Appends a `NumberBoundedMeterElement` component.
      *
      * @remarks
-     * Bounded numeric meter representation (read-only progress / score bar).
+     * Displays a scalar value against a minimum-to-maximum range. Supply comparable bounds and a value in that range; optional label and unit customize the textual readout without changing the meter scale.
      *
      * @param value - Numeric value
+  
+    Current measurement or score represented by the meter.
      * @param options - Optional component settings (minimum, maximum, label, unit, modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2097,29 +3328,19 @@ export declare class UiContainerBuilder {
         modifiers?: PrimitiveModifiers;
     }): this;
     /**
-     * Appends a `BooleanPlainElement` component.
-     *
-     * @remarks
-     * Plain boolean value representation (textual "true" / "false").
-     *
-     * @param value - Boolean state value
-     * @param options - Optional component settings (modifiers).
-     * @returns This builder instance for method chaining.
-     */
-    addBooleanPlain(value: boolean, options?: {
-        modifiers?: PrimitiveModifiers;
-    }): this;
-    /**
-     * Appends a `BooleanBadgeElement` component.
+     * Appends a `BooleanElement` component.
      *
      * @remarks
-     * Visual badge pill representation of a boolean state.
+     * Displays a boolean state using text or a badge. The representation determines whether true/false labels or a colored badge are used; configured labels and variant are presentation choices only.
      *
      * @param value - Boolean state value
-     * @param options - Optional component settings (trueLabel (defaults to `true`), falseLabel (defaults to `false`), variant (defaults to `neutral`), modifiers).
+  
+    State to display. This remains a boolean value in the data model even when the renderer substitutes custom labels.
+     * @param options - Optional component settings (representation (defaults to `plain`), trueLabel (defaults to `true`), falseLabel (defaults to `false`), variant (defaults to `neutral`), modifiers).
      * @returns This builder instance for method chaining.
      */
-    addBooleanBadge(value: boolean, options?: {
+    addBoolean(value: boolean, options?: {
+        representation?: BooleanRepresentation;
         trueLabel?: string;
         falseLabel?: string;
         variant?: BadgeVariant;
@@ -2129,9 +3350,11 @@ export declare class UiContainerBuilder {
      * Appends a `TimestampElement` component.
      *
      * @remarks
-     * Formatted date and time representation.
+     * Displays an epoch timestamp using a selected date/time format. The input is a count of milliseconds, not seconds; relative formatting is interpreted by the consumer.
      *
      * @param value - The timestamp in milliseconds
+  
+    Unix epoch timestamp measured in milliseconds. Convert seconds-based timestamps before assigning this value.
      * @param options - Optional component settings (format (defaults to `datetime`), modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2143,9 +3366,11 @@ export declare class UiContainerBuilder {
      * Appends a `ImageReferenceElement` component.
      *
      * @remarks
-     * Thumbnail image reference with placeholder fallback handling.
+     * References an image source for thumbnail rendering and provides accessible text and a fallback source. The client determines loading, sizing, and placeholder behavior.
      *
      * @param src - Image source URI (HTTPS URL, base64 data URI, or asset path)
+  
+    Source URI understood by the client renderer. Supported forms include HTTPS locations, base64 data URIs, and client asset paths; this field is not raw image bytes.
      * @param options - Optional component settings (alt, aspectRatio (defaults to `1:1`), placeholder).
      * @returns This builder instance for method chaining.
      */
@@ -2158,9 +3383,11 @@ export declare class UiContainerBuilder {
      * Appends a `ImageReferenceElement` component.
      *
      * @remarks
-     * Thumbnail image reference with placeholder fallback handling.
+     * References an image source for thumbnail rendering and provides accessible text and a fallback source. The client determines loading, sizing, and placeholder behavior.
      *
      * @param src - Image source URI (HTTPS URL, base64 data URI, or asset path)
+  
+    Source URI understood by the client renderer. Supported forms include HTTPS locations, base64 data URIs, and client asset paths; this field is not raw image bytes.
      * @param options - Optional component settings (alt, aspectRatio (defaults to `1:1`), placeholder).
      * @returns This builder instance for method chaining.
      */
@@ -2173,9 +3400,11 @@ export declare class UiContainerBuilder {
      * Appends a `MarkdownBlockElement` component.
      *
      * @remarks
-     * Full Markdown fallback block rendered with core typographic hierarchy, spacing, and styling.
+     * Use this custom-renderer escape hatch when the structured ViewKit elements cannot express the required rich text. Markdown rendering is a presentation fallback; prefer typed elements when consumers need to inspect individual values.
      *
      * @param content - Raw Markdown markup content
+  
+    Markdown source consumed by the client renderer. The schema treats it as an opaque string and does not validate the markup or its links.
      * @param options - Optional component settings (modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2186,9 +3415,11 @@ export declare class UiContainerBuilder {
      * Appends a `MarkdownBlockElement` component.
      *
      * @remarks
-     * Full Markdown fallback block rendered with core typographic hierarchy, spacing, and styling.
+     * Use this custom-renderer escape hatch when the structured ViewKit elements cannot express the required rich text. Markdown rendering is a presentation fallback; prefer typed elements when consumers need to inspect individual values.
      *
      * @param content - Raw Markdown markup content
+  
+    Markdown source consumed by the client renderer. The schema treats it as an opaque string and does not validate the markup or its links.
      * @param options - Optional component settings (modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2199,9 +3430,11 @@ export declare class UiContainerBuilder {
      * Appends a `HtmlBlockElement` component.
      *
      * @remarks
-     * Sandboxed HTML rendering escape hatch.
+     * Use only when structured elements or Markdown cannot represent the required content. Rendering occurs in a sandboxed host context, but callers should still avoid embedding untrusted content and should not assume access to application privileges.
      *
      * @param content - Raw HTML markup content
+  
+    HTML source passed to the custom renderer. This is an opaque string, not a typed or sanitized DOM structure.
      * @param options - Optional component settings (modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2212,9 +3445,11 @@ export declare class UiContainerBuilder {
      * Appends a `HtmlBlockElement` component.
      *
      * @remarks
-     * Sandboxed HTML rendering escape hatch.
+     * Use only when structured elements or Markdown cannot represent the required content. Rendering occurs in a sandboxed host context, but callers should still avoid embedding untrusted content and should not assume access to application privileges.
      *
      * @param content - Raw HTML markup content
+  
+    HTML source passed to the custom renderer. This is an opaque string, not a typed or sanitized DOM structure.
      * @param options - Optional component settings (modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2225,36 +3460,41 @@ export declare class UiContainerBuilder {
      * Appends a `MultiSlotElement` component.
      *
      * @remarks
-     * Multi-slot horizontal row with declared column width proportions.
-     * Examples: "1/3 + 2/3", "equal thirds", "1/4 + 3/4".
+     * Use this layout when a row needs explicit regions with independently controlled widths. Each slot contains one child element; unlike FlowingElement, the layout does not automatically wrap a sequence of children.
      *
      * @param slots - List of slots comprising the row
-     * @param options - Optional component settings (proportions).
+  
+    Ordered slots in the row. Each slot's width is a percentage; arrange slot definitions in the intended visual order.
      * @returns This builder instance for method chaining.
      */
-    addMultiSlot(slots: Slot[], options?: {
-        proportions?: string;
-    }): this;
+    addMultiSlot(slots: Slot[]): this;
     /**
      * Appends a `FlowingElement` component.
      *
      * @remarks
-     * Flowing inline layout container with automatic line wrapping.
-     * Renders child elements horizontally in sequence, automatically wrapping to the next line when space runs out.
+     * Use for compact related values that should flow horizontally and wrap naturally at the available width. Child order is preserved; an optional separator is placed between neighboring children.
      *
      * @param elements - List of child elements rendered sequentially with line wrapping
+  
+    Ordered children rendered in the flow. The client wraps them as needed rather than requiring callers to calculate line breaks.
+     * @param options - Optional component settings (separator).
      * @returns This builder instance for method chaining.
      */
-    addFlowing(elements: UiElement[]): this;
+    addFlowing(elements: UiElement[], options?: {
+        separator?: Separator;
+    }): this;
     /**
      * Appends a `LabelValueElement` component.
      *
      * @remarks
-     * Standard label and value row.
-     * Displays a muted label on the left and value representation on the right with a vertical dividing line.
+     * Represents one named value with a muted left-hand label and a right-hand visual element. Use it for a single field; use TableElement for repeated rows or column-aligned data.
      *
      * @param label - Key or descriptive label displayed muted on the left
+  
+    Human-readable name for the value. This text is rendered as the row label rather than as a separate UiElement.
      * @param value - Rendered value element on the right
+  
+    Value content rendered in the right-hand region. It may be a primitive or a nested structural element.
      * @param options - Optional component settings (withDivider (defaults to `false`)).
      * @returns This builder instance for method chaining.
      */
@@ -2265,15 +3505,15 @@ export declare class UiContainerBuilder {
      * Appends a `TableElement` component.
      *
      * @remarks
-     * Structured tabular data representation.
-     * Supports header/borderless modes, 2-column key-value tables, and 3-column data tables.
+     * Use for data that benefits from aligned rows and columns, including key/value and multi-column tables. Supply rows in display order; explicit columns are optional, and divider/striping flags independently control visual separators and alternating backgrounds.
      *
      * @param rows - Tabular data rows
-     * @param options - Optional component settings (hasHeader (defaults to `true`), isStriped (defaults to `false`), withColumnSeparators (defaults to `false`), withRowSeparators (defaults to `false`), columns).
+  
+    Ordered table rows. Each row's cells correspond positionally to the declared columns.
+     * @param options - Optional component settings (isStriped (defaults to `false`), withColumnSeparators (defaults to `false`), withRowSeparators (defaults to `false`), columns).
      * @returns This builder instance for method chaining.
      */
     addTable(rows: TableRow[], options?: {
-        hasHeader?: boolean;
         isStriped?: boolean;
         withColumnSeparators?: boolean;
         withRowSeparators?: boolean;
@@ -2283,9 +3523,11 @@ export declare class UiContainerBuilder {
      * Appends a `RepeatingGroupElement` component.
      *
      * @remarks
-     * Repeating group container where entries share uniform structure and retain per-entry labels.
+     * Groups a sequence of labeled entries under one optional section title. Use it when records have the same general presentation but need their own labels.
      *
      * @param entries - List of repeated entry records
+  
+    Entries in display order. Each entry supplies its own label and content.
      * @param options - Optional component settings (title).
      * @returns This builder instance for method chaining.
      */
@@ -2296,10 +3538,14 @@ export declare class UiContainerBuilder {
      * Appends a `CollapsibleGroupElement` component.
      *
      * @remarks
-     * Collapsible disclosure container (accordion) with summary badge.
+     * Groups nested content behind a disclosure control. The title names the group, summary can provide a compact status indicator, and defaultExpanded controls only the initial state.
      *
      * @param title - Group title (e.g. "Show specimen details")
+  
+    Text shown on the disclosure control. Use a concise action or section name that remains meaningful while the content is collapsed.
      * @param elements - Nested content elements revealed when expanded
+  
+    Ordered child elements made visible by expanding the group.
      * @param options - Optional component settings (summary, defaultExpanded (defaults to `false`)).
      * @returns This builder instance for method chaining.
      */
@@ -2311,7 +3557,7 @@ export declare class UiContainerBuilder {
      * Appends a `DividerElement` component.
      *
      * @remarks
-     * Visual hairline separator separating sections or element groups.
+     * A standalone visual separator for dividing adjacent sections or element groups. Use the divider flags on tables or rows when the separator is part of that structure.
      *
      * @param options - Optional component settings (style (defaults to `hairline`)).
      * @returns This builder instance for method chaining.
@@ -2371,7 +3617,7 @@ export declare const UiContainer: {
  * Functional helper to create a `UiContainerClass` instance directly.
  *
  * @remarks
- * Container model representing an ordered list of visual elements.
+ * Provides the shared root content collection inherited by cards and other root models. The order of elements is significant and is preserved by the renderer.
  *
  * @param options - Optional configuration properties.
  * @returns A strongly-typed `UiContainerClass` instance.
@@ -2383,7 +3629,7 @@ export declare function createUiContainer(options?: {
  * Parses a JSON string or raw object into a validated `UiContainerClass` instance.
  *
  * @remarks
- * Container model representing an ordered list of visual elements.
+ * Provides the shared root content collection inherited by cards and other root models. The order of elements is significant and is preserved by the renderer.
  *
  * @param json - JSON string or parsed JavaScript object to validate and hydrate.
  * @param withDeepValidation - Whether to recursively validate all nested child entities.
@@ -2394,8 +3640,7 @@ export declare function parseUiContainer(json: string | unknown, withDeepValidat
  * Fluent builder for constructing strongly-typed `UiCard` instances.
  *
  * @remarks
- * Root Card container model.
- * Represents a complete feature card rendered inside the 360px panel.
+ * A complete card has a required title and ordered content inherited from UiContainer. It is designed for the feature-card surface; description and actions supplement the content, with action controls rendered separately from the element list.
  */
 export declare class UiCardBuilder {
     private readonly _title;
@@ -2406,12 +3651,16 @@ export declare class UiCardBuilder {
      * Initializes a new `UiCardBuilder`.
      *
      * @param title - Human-readable feature title displayed in the card header
+  
+    Primary heading for the card. Keep it concise enough for the card header; longer explanatory text belongs in description or elements.
      */
     constructor(title: string);
     /**
      * Sets the `description` property on this builder.
      *
      * @param description - Optional neutral subtitle / description for the feature
+  
+    Brief secondary context shown with the title. Use the content elements for detailed information rather than placing an entire report in this field.
      * @returns This builder instance for method chaining.
      */
     description(description: string): this;
@@ -2444,40 +3693,47 @@ export declare class UiCardBuilder {
      */
     addElements(...items: UiElement[]): this;
     /**
-     * Appends a `StringShortElement` component.
+     * Appends a `StringElement` component.
      *
      * @remarks
-     * Short string primitive element.
-     * Supports plain text or compact chip pill presentation.
+     * Use this primitive for one textual value when a structured label/value row is unnecessary. Choose multiline for content whose line breaks should remain visible; modifiers apply presentation traits without changing the underlying value.
      *
      * @param value - Text value
+  
+    Text to render. Supply plain text; this field is not a Markdown or HTML document.
      * @param options - Optional component settings (representation (defaults to `plain`), modifiers).
      * @returns This builder instance for method chaining.
      */
-    addStringShort(value: string, options?: {
-        representation?: StringShortRepresentation;
+    addString(value: string, options?: {
+        representation?: StringRepresentation;
         modifiers?: PrimitiveModifiers;
     }): this;
     /**
-     * Appends a `StringLongElement` component.
+     * Appends a `StringsElement` component.
      *
      * @remarks
-     * Multiline text block primitive element for descriptions, comments, or prose.
+     * Use this primitive when several related strings should be rendered as one compact sequence. The client preserves the array order and inserts the selected separator between values.
      *
-     * @param value - Text value
-     * @param options - Optional component settings (modifiers).
+     * @param values - Array of string values
+  
+    Values to render in order. Each array entry remains a distinct item for chip presentation and is not parsed as a delimited string.
+     * @param options - Optional component settings (representation (defaults to `plain`), separator, modifiers).
      * @returns This builder instance for method chaining.
      */
-    addStringLong(value: string, options?: {
+    addStrings(values: string[], options?: {
+        representation?: StringRepresentation;
+        separator?: Separator;
         modifiers?: PrimitiveModifiers;
     }): this;
     /**
      * Appends a `StringCodeElement` component.
      *
      * @remarks
-     * Monospace code block or formatted code snippet representation.
+     * Use for source-like or preformatted textual content that should be rendered in a code-oriented style. The language is a presentation hint; the content is not parsed or validated as code by this contract.
      *
      * @param value - Text value
+  
+    Code or text snippet to display. Include any desired line breaks in this string.
      * @param options - Optional component settings (language, modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2489,9 +3745,11 @@ export declare class UiCardBuilder {
      * Appends a `XmlElement` component.
      *
      * @remarks
-     * XML markup code block element.
+     * Specialized code-oriented element for XML content. It uses the custom XML renderer rather than requiring consumers to construct a generic code block.
      *
      * @param value - XML content value
+  
+    XML markup to render. The contract carries the source text; it does not guarantee that the document is well-formed.
      * @param options - Optional component settings (modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2502,9 +3760,11 @@ export declare class UiCardBuilder {
      * Appends a `JsonElement` component.
      *
      * @remarks
-     * JSON data or structure representation element.
+     * Specialized representation for JSON text. Supply serialized JSON when consumers should display a JSON document; this field is a string and is not structurally validated here.
      *
      * @param value - JSON content value
+  
+    Serialized JSON text to render. No parsing or schema validation is implied by this element.
      * @param options - Optional component settings (modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2515,9 +3775,11 @@ export declare class UiCardBuilder {
      * Appends a `StringUrlElement` component.
      *
      * @remarks
-     * Hyperlink representation for external or internal URL navigation.
+     * Use this element when displayed text should also behave as a link. Unlike StringElement, the value is a navigation destination and may be paired with a separate human-readable label.
      *
      * @param value - Target URL or navigation destination
+  
+    Destination associated with the link. Supply a URL or client-recognized navigation target supported by the renderer.
      * @param options - Optional component settings (label, modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2529,9 +3791,11 @@ export declare class UiCardBuilder {
      * Appends a `IdentifierElement` component.
      *
      * @remarks
-     * Monospace semantic identifier representation.
+     * Use for identifiers, hashes, and other machine-oriented strings that benefit from monospace styling. The value remains text and is not resolved as a Picteus entity.
      *
      * @param value - Identifier string value
+  
+    Identifier text to display, such as an opaque ID or hash. Avoid embedding presentation markup in the value.
      * @param options - Optional component settings (modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2542,22 +3806,44 @@ export declare class UiCardBuilder {
      * Appends a `RatioElement` component.
      *
      * @remarks
-     * Aspect ratio representation (e.g. "16:9", "4:3", "1:1").
+     * Displays a numeric aspect ratio as a ratio expression. Provide a positive value meaningful to the surrounding content; this type does not encode the source image dimensions.
      *
      * @param value - Aspect ratio numerical expression
+  
+    Numeric ratio value used by the renderer to produce an aspect-ratio display.
      * @param options - Optional component settings (modifiers).
      * @returns This builder instance for method chaining.
      */
     addRatio(value: number, options?: {
         modifiers?: PrimitiveModifiers;
     }): this;
+    /**
+     * Appends a `DimensionsElement` component.
+     *
+     * @remarks
+     * Displays a width/height pair as image dimensions. Both values are positive pixel counts; together they describe dimensions, not an aspect ratio or a resize request.
+     *
+     * @param width - Width in pixels
+  
+    Horizontal pixel count. Values below one are rejected by the schema constraint.
+     * @param height - Height in pixels
+  
+    Vertical pixel count. Values below one are rejected by the schema constraint.
+     * @param options - Optional component settings (modifiers).
+     * @returns This builder instance for method chaining.
+     */
+    addDimensions(width: number, height: number, options?: {
+        modifiers?: BaseModifiers;
+    }): this;
     /**
      * Appends a `ColourElement` component.
      *
      * @remarks
-     * Single color representation with hex value, shape/size styling, text display toggle, and copy affordance.
+     * Displays one color swatch with configurable geometry and optional adjacent text. Supply the color as a hexadecimal string; the schema leaves exact accepted hex formats to the renderer.
      *
      * @param value - Hexadecimal color code
+  
+    Color value used to draw the swatch. Use a hexadecimal representation supported by the client renderer.
      * @param options - Optional component settings (label, showText (defaults to `true`), shape (defaults to `circle`), size (defaults to `medium`), modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2572,9 +3858,11 @@ export declare class UiCardBuilder {
      * Appends a `ColourElement` component.
      *
      * @remarks
-     * Single color representation with hex value, shape/size styling, text display toggle, and copy affordance.
+     * Displays one color swatch with configurable geometry and optional adjacent text. Supply the color as a hexadecimal string; the schema leaves exact accepted hex formats to the renderer.
      *
      * @param value - Hexadecimal color code
+  
+    Color value used to draw the swatch. Use a hexadecimal representation supported by the client renderer.
      * @param options - Optional component settings (label, showText (defaults to `true`), shape (defaults to `circle`), size (defaults to `medium`), modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2589,9 +3877,11 @@ export declare class UiCardBuilder {
      * Appends a `NumberUnboundedElement` component.
      *
      * @remarks
-     * Plain unbounded numeric value primitive element.
+     * Displays a numeric value without a progress scale or rating interpretation. Use unit to communicate the measurement context; no range is imposed by this model.
      *
      * @param value - Numeric value
+  
+    Number to display. Its meaning and any valid range are defined by the producing feature.
      * @param options - Optional component settings (unit, modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2603,9 +3893,11 @@ export declare class UiCardBuilder {
      * Appends a `NumberBoundedStarsElement` component.
      *
      * @remarks
-     * Bounded numeric rating represented as visual stars.
+     * Displays a score on a star scale. Keep value within the scale from zero through maximum; this model declares the scale metadata but does not impose a numeric validation bound.
      *
      * @param value - Numeric rating score
+  
+    Score represented by the filled portion of the star display.
      * @param options - Optional component settings (maximum, modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2617,9 +3909,11 @@ export declare class UiCardBuilder {
      * Appends a `NumberBoundedStarsElement` component.
      *
      * @remarks
-     * Bounded numeric rating represented as visual stars.
+     * Displays a score on a star scale. Keep value within the scale from zero through maximum; this model declares the scale metadata but does not impose a numeric validation bound.
      *
      * @param value - Numeric rating score
+  
+    Score represented by the filled portion of the star display.
      * @param options - Optional component settings (maximum, modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2631,9 +3925,11 @@ export declare class UiCardBuilder {
      * Appends a `NumberBoundedMeterElement` component.
      *
      * @remarks
-     * Bounded numeric meter representation (read-only progress / score bar).
+     * Displays a scalar value against a minimum-to-maximum range. Supply comparable bounds and a value in that range; optional label and unit customize the textual readout without changing the meter scale.
      *
      * @param value - Numeric value
+  
+    Current measurement or score represented by the meter.
      * @param options - Optional component settings (minimum, maximum, label, unit, modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2648,9 +3944,11 @@ export declare class UiCardBuilder {
      * Appends a `NumberBoundedMeterElement` component.
      *
      * @remarks
-     * Bounded numeric meter representation (read-only progress / score bar).
+     * Displays a scalar value against a minimum-to-maximum range. Supply comparable bounds and a value in that range; optional label and unit customize the textual readout without changing the meter scale.
      *
      * @param value - Numeric value
+  
+    Current measurement or score represented by the meter.
      * @param options - Optional component settings (minimum, maximum, label, unit, modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2662,29 +3960,19 @@ export declare class UiCardBuilder {
         modifiers?: PrimitiveModifiers;
     }): this;
     /**
-     * Appends a `BooleanPlainElement` component.
-     *
-     * @remarks
-     * Plain boolean value representation (textual "true" / "false").
-     *
-     * @param value - Boolean state value
-     * @param options - Optional component settings (modifiers).
-     * @returns This builder instance for method chaining.
-     */
-    addBooleanPlain(value: boolean, options?: {
-        modifiers?: PrimitiveModifiers;
-    }): this;
-    /**
-     * Appends a `BooleanBadgeElement` component.
+     * Appends a `BooleanElement` component.
      *
      * @remarks
-     * Visual badge pill representation of a boolean state.
+     * Displays a boolean state using text or a badge. The representation determines whether true/false labels or a colored badge are used; configured labels and variant are presentation choices only.
      *
      * @param value - Boolean state value
-     * @param options - Optional component settings (trueLabel (defaults to `true`), falseLabel (defaults to `false`), variant (defaults to `neutral`), modifiers).
+  
+    State to display. This remains a boolean value in the data model even when the renderer substitutes custom labels.
+     * @param options - Optional component settings (representation (defaults to `plain`), trueLabel (defaults to `true`), falseLabel (defaults to `false`), variant (defaults to `neutral`), modifiers).
      * @returns This builder instance for method chaining.
      */
-    addBooleanBadge(value: boolean, options?: {
+    addBoolean(value: boolean, options?: {
+        representation?: BooleanRepresentation;
         trueLabel?: string;
         falseLabel?: string;
         variant?: BadgeVariant;
@@ -2694,9 +3982,11 @@ export declare class UiCardBuilder {
      * Appends a `TimestampElement` component.
      *
      * @remarks
-     * Formatted date and time representation.
+     * Displays an epoch timestamp using a selected date/time format. The input is a count of milliseconds, not seconds; relative formatting is interpreted by the consumer.
      *
      * @param value - The timestamp in milliseconds
+  
+    Unix epoch timestamp measured in milliseconds. Convert seconds-based timestamps before assigning this value.
      * @param options - Optional component settings (format (defaults to `datetime`), modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2708,9 +3998,11 @@ export declare class UiCardBuilder {
      * Appends a `ImageReferenceElement` component.
      *
      * @remarks
-     * Thumbnail image reference with placeholder fallback handling.
+     * References an image source for thumbnail rendering and provides accessible text and a fallback source. The client determines loading, sizing, and placeholder behavior.
      *
      * @param src - Image source URI (HTTPS URL, base64 data URI, or asset path)
+  
+    Source URI understood by the client renderer. Supported forms include HTTPS locations, base64 data URIs, and client asset paths; this field is not raw image bytes.
      * @param options - Optional component settings (alt, aspectRatio (defaults to `1:1`), placeholder).
      * @returns This builder instance for method chaining.
      */
@@ -2723,9 +4015,11 @@ export declare class UiCardBuilder {
      * Appends a `ImageReferenceElement` component.
      *
      * @remarks
-     * Thumbnail image reference with placeholder fallback handling.
+     * References an image source for thumbnail rendering and provides accessible text and a fallback source. The client determines loading, sizing, and placeholder behavior.
      *
      * @param src - Image source URI (HTTPS URL, base64 data URI, or asset path)
+  
+    Source URI understood by the client renderer. Supported forms include HTTPS locations, base64 data URIs, and client asset paths; this field is not raw image bytes.
      * @param options - Optional component settings (alt, aspectRatio (defaults to `1:1`), placeholder).
      * @returns This builder instance for method chaining.
      */
@@ -2738,9 +4032,11 @@ export declare class UiCardBuilder {
      * Appends a `MarkdownBlockElement` component.
      *
      * @remarks
-     * Full Markdown fallback block rendered with core typographic hierarchy, spacing, and styling.
+     * Use this custom-renderer escape hatch when the structured ViewKit elements cannot express the required rich text. Markdown rendering is a presentation fallback; prefer typed elements when consumers need to inspect individual values.
      *
      * @param content - Raw Markdown markup content
+  
+    Markdown source consumed by the client renderer. The schema treats it as an opaque string and does not validate the markup or its links.
      * @param options - Optional component settings (modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2751,9 +4047,11 @@ export declare class UiCardBuilder {
      * Appends a `MarkdownBlockElement` component.
      *
      * @remarks
-     * Full Markdown fallback block rendered with core typographic hierarchy, spacing, and styling.
+     * Use this custom-renderer escape hatch when the structured ViewKit elements cannot express the required rich text. Markdown rendering is a presentation fallback; prefer typed elements when consumers need to inspect individual values.
      *
      * @param content - Raw Markdown markup content
+  
+    Markdown source consumed by the client renderer. The schema treats it as an opaque string and does not validate the markup or its links.
      * @param options - Optional component settings (modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2764,9 +4062,11 @@ export declare class UiCardBuilder {
      * Appends a `HtmlBlockElement` component.
      *
      * @remarks
-     * Sandboxed HTML rendering escape hatch.
+     * Use only when structured elements or Markdown cannot represent the required content. Rendering occurs in a sandboxed host context, but callers should still avoid embedding untrusted content and should not assume access to application privileges.
      *
      * @param content - Raw HTML markup content
+  
+    HTML source passed to the custom renderer. This is an opaque string, not a typed or sanitized DOM structure.
      * @param options - Optional component settings (modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2777,9 +4077,11 @@ export declare class UiCardBuilder {
      * Appends a `HtmlBlockElement` component.
      *
      * @remarks
-     * Sandboxed HTML rendering escape hatch.
+     * Use only when structured elements or Markdown cannot represent the required content. Rendering occurs in a sandboxed host context, but callers should still avoid embedding untrusted content and should not assume access to application privileges.
      *
      * @param content - Raw HTML markup content
+  
+    HTML source passed to the custom renderer. This is an opaque string, not a typed or sanitized DOM structure.
      * @param options - Optional component settings (modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2790,36 +4092,41 @@ export declare class UiCardBuilder {
      * Appends a `MultiSlotElement` component.
      *
      * @remarks
-     * Multi-slot horizontal row with declared column width proportions.
-     * Examples: "1/3 + 2/3", "equal thirds", "1/4 + 3/4".
+     * Use this layout when a row needs explicit regions with independently controlled widths. Each slot contains one child element; unlike FlowingElement, the layout does not automatically wrap a sequence of children.
      *
      * @param slots - List of slots comprising the row
-     * @param options - Optional component settings (proportions).
+  
+    Ordered slots in the row. Each slot's width is a percentage; arrange slot definitions in the intended visual order.
      * @returns This builder instance for method chaining.
      */
-    addMultiSlot(slots: Slot[], options?: {
-        proportions?: string;
-    }): this;
+    addMultiSlot(slots: Slot[]): this;
     /**
      * Appends a `FlowingElement` component.
      *
      * @remarks
-     * Flowing inline layout container with automatic line wrapping.
-     * Renders child elements horizontally in sequence, automatically wrapping to the next line when space runs out.
+     * Use for compact related values that should flow horizontally and wrap naturally at the available width. Child order is preserved; an optional separator is placed between neighboring children.
      *
      * @param elements - List of child elements rendered sequentially with line wrapping
+  
+    Ordered children rendered in the flow. The client wraps them as needed rather than requiring callers to calculate line breaks.
+     * @param options - Optional component settings (separator).
      * @returns This builder instance for method chaining.
      */
-    addFlowing(elements: UiElement[]): this;
+    addFlowing(elements: UiElement[], options?: {
+        separator?: Separator;
+    }): this;
     /**
      * Appends a `LabelValueElement` component.
      *
      * @remarks
-     * Standard label and value row.
-     * Displays a muted label on the left and value representation on the right with a vertical dividing line.
+     * Represents one named value with a muted left-hand label and a right-hand visual element. Use it for a single field; use TableElement for repeated rows or column-aligned data.
      *
      * @param label - Key or descriptive label displayed muted on the left
+  
+    Human-readable name for the value. This text is rendered as the row label rather than as a separate UiElement.
      * @param value - Rendered value element on the right
+  
+    Value content rendered in the right-hand region. It may be a primitive or a nested structural element.
      * @param options - Optional component settings (withDivider (defaults to `false`)).
      * @returns This builder instance for method chaining.
      */
@@ -2830,15 +4137,15 @@ export declare class UiCardBuilder {
      * Appends a `TableElement` component.
      *
      * @remarks
-     * Structured tabular data representation.
-     * Supports header/borderless modes, 2-column key-value tables, and 3-column data tables.
+     * Use for data that benefits from aligned rows and columns, including key/value and multi-column tables. Supply rows in display order; explicit columns are optional, and divider/striping flags independently control visual separators and alternating backgrounds.
      *
      * @param rows - Tabular data rows
-     * @param options - Optional component settings (hasHeader (defaults to `true`), isStriped (defaults to `false`), withColumnSeparators (defaults to `false`), withRowSeparators (defaults to `false`), columns).
+  
+    Ordered table rows. Each row's cells correspond positionally to the declared columns.
+     * @param options - Optional component settings (isStriped (defaults to `false`), withColumnSeparators (defaults to `false`), withRowSeparators (defaults to `false`), columns).
      * @returns This builder instance for method chaining.
      */
     addTable(rows: TableRow[], options?: {
-        hasHeader?: boolean;
         isStriped?: boolean;
         withColumnSeparators?: boolean;
         withRowSeparators?: boolean;
@@ -2848,9 +4155,11 @@ export declare class UiCardBuilder {
      * Appends a `RepeatingGroupElement` component.
      *
      * @remarks
-     * Repeating group container where entries share uniform structure and retain per-entry labels.
+     * Groups a sequence of labeled entries under one optional section title. Use it when records have the same general presentation but need their own labels.
      *
      * @param entries - List of repeated entry records
+  
+    Entries in display order. Each entry supplies its own label and content.
      * @param options - Optional component settings (title).
      * @returns This builder instance for method chaining.
      */
@@ -2861,10 +4170,14 @@ export declare class UiCardBuilder {
      * Appends a `CollapsibleGroupElement` component.
      *
      * @remarks
-     * Collapsible disclosure container (accordion) with summary badge.
+     * Groups nested content behind a disclosure control. The title names the group, summary can provide a compact status indicator, and defaultExpanded controls only the initial state.
      *
      * @param title - Group title (e.g. "Show specimen details")
+  
+    Text shown on the disclosure control. Use a concise action or section name that remains meaningful while the content is collapsed.
      * @param elements - Nested content elements revealed when expanded
+  
+    Ordered child elements made visible by expanding the group.
      * @param options - Optional component settings (summary, defaultExpanded (defaults to `false`)).
      * @returns This builder instance for method chaining.
      */
@@ -2876,7 +4189,7 @@ export declare class UiCardBuilder {
      * Appends a `DividerElement` component.
      *
      * @remarks
-     * Visual hairline separator separating sections or element groups.
+     * A standalone visual separator for dividing adjacent sections or element groups. Use the divider flags on tables or rows when the separator is part of that structure.
      *
      * @param options - Optional component settings (style (defaults to `hairline`)).
      * @returns This builder instance for method chaining.
@@ -2909,6 +4222,8 @@ export declare const UiCard: {
      * Creates a new fluent builder for constructing a `UiCard`.
      *
      * @param title - Human-readable feature title displayed in the card header
+  
+    Primary heading for the card. Keep it concise enough for the card header; longer explanatory text belongs in description or elements.
      * @returns A new `UiCardBuilder` instance.
      */
     builder(title: string): UiCardBuilder;
@@ -2940,10 +4255,11 @@ export declare const UiCard: {
  * Functional helper to create a `UiCardClass` instance directly.
  *
  * @remarks
- * Root Card container model.
- * Represents a complete feature card rendered inside the 360px panel.
+ * A complete card has a required title and ordered content inherited from UiContainer. It is designed for the feature-card surface; description and actions supplement the content, with action controls rendered separately from the element list.
  *
  * @param title - Human-readable feature title displayed in the card header
+
+Primary heading for the card. Keep it concise enough for the card header; longer explanatory text belongs in description or elements.
  * @param options - Optional configuration properties.
  * @returns A strongly-typed `UiCardClass` instance.
  */
@@ -2956,8 +4272,7 @@ export declare function createUiCard(title: string, options?: {
  * Parses a JSON string or raw object into a validated `UiCardClass` instance.
  *
  * @remarks
- * Root Card container model.
- * Represents a complete feature card rendered inside the 360px panel.
+ * A complete card has a required title and ordered content inherited from UiContainer. It is designed for the feature-card surface; description and actions supplement the content, with action controls rendered separately from the element list.
  *
  * @param json - JSON string or parsed JavaScript object to validate and hydrate.
  * @param withDeepValidation - Whether to recursively validate all nested child entities.
@@ -2968,9 +4283,11 @@ export declare function parseUiCard(json: string | unknown, withDeepValidation?:
  * Creates a `TruncateOptions` component instance.
  *
  * @remarks
- * Truncation configuration for long textual content with optional expand affordance.
+ * Controls how a renderer abbreviates long text. The character limit is a presentation threshold rather than a validation limit; showMore lets the user reveal the remaining text.
  *
  * @param characterLimit - Maximum number of characters to display before truncating
+
+Threshold after which the renderer can shorten the displayed text. This does not constrain the stored string or remove its undisplayed content.
  * @param options - Optional settings (showMore (defaults to `true`)).
  * @returns A strongly-typed `TruncateOptions` object.
  */
@@ -2981,7 +4298,7 @@ export declare function truncateOptions(characterLimit: number, options?: {
  * Creates a `BaseModifiers` component instance.
  *
  * @remarks
- * Base modifier traits for elements that support copy affordance.
+ * Common optional presentation traits shared by primitive values and content renderers. Modifiers affect how content is displayed or copied; they do not transform the source value.
  *
  * @param options - Optional settings (copyable).
  * @returns A strongly-typed `BaseModifiers` object.
@@ -2993,7 +4310,7 @@ export declare function baseModifiers(options?: {
  * Creates a `PrimitiveModifiers` component instance.
  *
  * @remarks
- * Common modifier traits that can be attached to primitive elements.
+ * Extends BaseModifiers with text styling controls. Defaults provide normal weight, medium intensity, and proportional text unless a feature explicitly overrides them.
  *
  * @param options - Optional settings (truncate, weight (defaults to `normal`), intensity (defaults to `medium`), monospace (defaults to `false`), copyable).
  * @returns A strongly-typed `PrimitiveModifiers` object.
@@ -3006,40 +4323,47 @@ export declare function primitiveModifiers(options?: {
     copyable?: boolean;
 }): PrimitiveModifiers;
 /**
- * Creates a `StringShortElement` component instance.
+ * Creates a `StringElement` component instance.
  *
  * @remarks
- * Short string primitive element.
- * Supports plain text or compact chip pill presentation.
+ * Use this primitive for one textual value when a structured label/value row is unnecessary. Choose multiline for content whose line breaks should remain visible; modifiers apply presentation traits without changing the underlying value.
  *
  * @param value - Text value
+
+Text to render. Supply plain text; this field is not a Markdown or HTML document.
  * @param options - Optional settings (representation (defaults to `plain`), modifiers).
- * @returns A strongly-typed `StringShortElement` object.
+ * @returns A strongly-typed `StringElement` object.
  */
-export declare function stringShort(value: string, options?: {
-    representation?: StringShortRepresentation;
+export declare function string(value: string, options?: {
+    representation?: StringRepresentation;
     modifiers?: PrimitiveModifiers;
-}): StringShortElement;
+}): StringElement;
 /**
- * Creates a `StringLongElement` component instance.
+ * Creates a `StringsElement` component instance.
  *
  * @remarks
- * Multiline text block primitive element for descriptions, comments, or prose.
+ * Use this primitive when several related strings should be rendered as one compact sequence. The client preserves the array order and inserts the selected separator between values.
  *
- * @param value - Text value
- * @param options - Optional settings (modifiers).
- * @returns A strongly-typed `StringLongElement` object.
+ * @param values - Array of string values
+
+Values to render in order. Each array entry remains a distinct item for chip presentation and is not parsed as a delimited string.
+ * @param options - Optional settings (representation (defaults to `plain`), separator, modifiers).
+ * @returns A strongly-typed `StringsElement` object.
  */
-export declare function stringLong(value: string, options?: {
+export declare function strings(values: string[], options?: {
+    representation?: StringRepresentation;
+    separator?: Separator;
     modifiers?: PrimitiveModifiers;
-}): StringLongElement;
+}): StringsElement;
 /**
  * Creates a `StringCodeElement` component instance.
  *
  * @remarks
- * Monospace code block or formatted code snippet representation.
+ * Use for source-like or preformatted textual content that should be rendered in a code-oriented style. The language is a presentation hint; the content is not parsed or validated as code by this contract.
  *
  * @param value - Text value
+
+Code or text snippet to display. Include any desired line breaks in this string.
  * @param options - Optional settings (language, modifiers).
  * @returns A strongly-typed `StringCodeElement` object.
  */
@@ -3051,9 +4375,11 @@ export declare function stringCode(value: string, options?: {
  * Creates a `XmlElement` component instance.
  *
  * @remarks
- * XML markup code block element.
+ * Specialized code-oriented element for XML content. It uses the custom XML renderer rather than requiring consumers to construct a generic code block.
  *
  * @param value - XML content value
+
+XML markup to render. The contract carries the source text; it does not guarantee that the document is well-formed.
  * @param options - Optional settings (modifiers).
  * @returns A strongly-typed `XmlElement` object.
  */
@@ -3064,9 +4390,11 @@ export declare function xml(value: string, options?: {
  * Creates a `JsonElement` component instance.
  *
  * @remarks
- * JSON data or structure representation element.
+ * Specialized representation for JSON text. Supply serialized JSON when consumers should display a JSON document; this field is a string and is not structurally validated here.
  *
  * @param value - JSON content value
+
+Serialized JSON text to render. No parsing or schema validation is implied by this element.
  * @param options - Optional settings (modifiers).
  * @returns A strongly-typed `JsonElement` object.
  */
@@ -3077,9 +4405,11 @@ export declare function json(value: string, options?: {
  * Creates a `StringUrlElement` component instance.
  *
  * @remarks
- * Hyperlink representation for external or internal URL navigation.
+ * Use this element when displayed text should also behave as a link. Unlike StringElement, the value is a navigation destination and may be paired with a separate human-readable label.
  *
  * @param value - Target URL or navigation destination
+
+Destination associated with the link. Supply a URL or client-recognized navigation target supported by the renderer.
  * @param options - Optional settings (label, modifiers).
  * @returns A strongly-typed `StringUrlElement` object.
  */
@@ -3091,9 +4421,11 @@ export declare function stringUrl(value: string, options?: {
  * Creates a `IdentifierElement` component instance.
  *
  * @remarks
- * Monospace semantic identifier representation.
+ * Use for identifiers, hashes, and other machine-oriented strings that benefit from monospace styling. The value remains text and is not resolved as a Picteus entity.
  *
  * @param value - Identifier string value
+
+Identifier text to display, such as an opaque ID or hash. Avoid embedding presentation markup in the value.
  * @param options - Optional settings (modifiers).
  * @returns A strongly-typed `IdentifierElement` object.
  */
@@ -3104,22 +4436,44 @@ export declare function identifier(value: string, options?: {
  * Creates a `RatioElement` component instance.
  *
  * @remarks
- * Aspect ratio representation (e.g. "16:9", "4:3", "1:1").
+ * Displays a numeric aspect ratio as a ratio expression. Provide a positive value meaningful to the surrounding content; this type does not encode the source image dimensions.
  *
  * @param value - Aspect ratio numerical expression
+
+Numeric ratio value used by the renderer to produce an aspect-ratio display.
  * @param options - Optional settings (modifiers).
  * @returns A strongly-typed `RatioElement` object.
  */
 export declare function ratio(value: number, options?: {
     modifiers?: PrimitiveModifiers;
 }): RatioElement;
+/**
+ * Creates a `DimensionsElement` component instance.
+ *
+ * @remarks
+ * Displays a width/height pair as image dimensions. Both values are positive pixel counts; together they describe dimensions, not an aspect ratio or a resize request.
+ *
+ * @param width - Width in pixels
+
+Horizontal pixel count. Values below one are rejected by the schema constraint.
+ * @param height - Height in pixels
+
+Vertical pixel count. Values below one are rejected by the schema constraint.
+ * @param options - Optional settings (modifiers).
+ * @returns A strongly-typed `DimensionsElement` object.
+ */
+export declare function dimensions(width: number, height: number, options?: {
+    modifiers?: BaseModifiers;
+}): DimensionsElement;
 /**
  * Creates a `ColourElement` component instance.
  *
  * @remarks
- * Single color representation with hex value, shape/size styling, text display toggle, and copy affordance.
+ * Displays one color swatch with configurable geometry and optional adjacent text. Supply the color as a hexadecimal string; the schema leaves exact accepted hex formats to the renderer.
  *
  * @param value - Hexadecimal color code
+
+Color value used to draw the swatch. Use a hexadecimal representation supported by the client renderer.
  * @param options - Optional settings (label, showText (defaults to `true`), shape (defaults to `circle`), size (defaults to `medium`), modifiers).
  * @returns A strongly-typed `ColourElement` object.
  */
@@ -3134,9 +4488,11 @@ export declare function colour(value: string, options?: {
  * Creates a `ColourElement` component instance.
  *
  * @remarks
- * Single color representation with hex value, shape/size styling, text display toggle, and copy affordance.
+ * Displays one color swatch with configurable geometry and optional adjacent text. Supply the color as a hexadecimal string; the schema leaves exact accepted hex formats to the renderer.
  *
  * @param value - Hexadecimal color code
+
+Color value used to draw the swatch. Use a hexadecimal representation supported by the client renderer.
  * @param options - Optional settings (label, showText (defaults to `true`), shape (defaults to `circle`), size (defaults to `medium`), modifiers).
  * @returns A strongly-typed `ColourElement` object.
  */
@@ -3151,9 +4507,11 @@ export declare function color(value: string, options?: {
  * Creates a `NumberUnboundedElement` component instance.
  *
  * @remarks
- * Plain unbounded numeric value primitive element.
+ * Displays a numeric value without a progress scale or rating interpretation. Use unit to communicate the measurement context; no range is imposed by this model.
  *
  * @param value - Numeric value
+
+Number to display. Its meaning and any valid range are defined by the producing feature.
  * @param options - Optional settings (unit, modifiers).
  * @returns A strongly-typed `NumberUnboundedElement` object.
  */
@@ -3165,9 +4523,11 @@ export declare function numberUnbounded(value: number, options?: {
  * Creates a `NumberBoundedStarsElement` component instance.
  *
  * @remarks
- * Bounded numeric rating represented as visual stars.
+ * Displays a score on a star scale. Keep value within the scale from zero through maximum; this model declares the scale metadata but does not impose a numeric validation bound.
  *
  * @param value - Numeric rating score
+
+Score represented by the filled portion of the star display.
  * @param options - Optional settings (maximum, modifiers).
  * @returns A strongly-typed `NumberBoundedStarsElement` object.
  */
@@ -3179,9 +4539,11 @@ export declare function numberBoundedStars(value: number, options?: {
  * Creates a `NumberBoundedStarsElement` component instance.
  *
  * @remarks
- * Bounded numeric rating represented as visual stars.
+ * Displays a score on a star scale. Keep value within the scale from zero through maximum; this model declares the scale metadata but does not impose a numeric validation bound.
  *
  * @param value - Numeric rating score
+
+Score represented by the filled portion of the star display.
  * @param options - Optional settings (maximum, modifiers).
  * @returns A strongly-typed `NumberBoundedStarsElement` object.
  */
@@ -3193,9 +4555,11 @@ export declare function numberStars(value: number, options?: {
  * Creates a `NumberBoundedMeterElement` component instance.
  *
  * @remarks
- * Bounded numeric meter representation (read-only progress / score bar).
+ * Displays a scalar value against a minimum-to-maximum range. Supply comparable bounds and a value in that range; optional label and unit customize the textual readout without changing the meter scale.
  *
  * @param value - Numeric value
+
+Current measurement or score represented by the meter.
  * @param options - Optional settings (minimum, maximum, label, unit, modifiers).
  * @returns A strongly-typed `NumberBoundedMeterElement` object.
  */
@@ -3210,9 +4574,11 @@ export declare function numberBoundedMeter(value: number, options?: {
  * Creates a `NumberBoundedMeterElement` component instance.
  *
  * @remarks
- * Bounded numeric meter representation (read-only progress / score bar).
+ * Displays a scalar value against a minimum-to-maximum range. Supply comparable bounds and a value in that range; optional label and unit customize the textual readout without changing the meter scale.
  *
  * @param value - Numeric value
+
+Current measurement or score represented by the meter.
  * @param options - Optional settings (minimum, maximum, label, unit, modifiers).
  * @returns A strongly-typed `NumberBoundedMeterElement` object.
  */
@@ -3224,41 +4590,33 @@ export declare function numberMeter(value: number, options?: {
     modifiers?: PrimitiveModifiers;
 }): NumberBoundedMeterElement;
 /**
- * Creates a `BooleanPlainElement` component instance.
- *
- * @remarks
- * Plain boolean value representation (textual "true" / "false").
- *
- * @param value - Boolean state value
- * @param options - Optional settings (modifiers).
- * @returns A strongly-typed `BooleanPlainElement` object.
- */
-export declare function booleanPlain(value: boolean, options?: {
-    modifiers?: PrimitiveModifiers;
-}): BooleanPlainElement;
-/**
- * Creates a `BooleanBadgeElement` component instance.
+ * Creates a `BooleanElement` component instance.
  *
  * @remarks
- * Visual badge pill representation of a boolean state.
+ * Displays a boolean state using text or a badge. The representation determines whether true/false labels or a colored badge are used; configured labels and variant are presentation choices only.
  *
  * @param value - Boolean state value
- * @param options - Optional settings (trueLabel (defaults to `true`), falseLabel (defaults to `false`), variant (defaults to `neutral`), modifiers).
- * @returns A strongly-typed `BooleanBadgeElement` object.
+
+State to display. This remains a boolean value in the data model even when the renderer substitutes custom labels.
+ * @param options - Optional settings (representation (defaults to `plain`), trueLabel (defaults to `true`), falseLabel (defaults to `false`), variant (defaults to `neutral`), modifiers).
+ * @returns A strongly-typed `BooleanElement` object.
  */
-export declare function booleanBadge(value: boolean, options?: {
+export declare function boolean(value: boolean, options?: {
+    representation?: BooleanRepresentation;
     trueLabel?: string;
     falseLabel?: string;
     variant?: BadgeVariant;
     modifiers?: PrimitiveModifiers;
-}): BooleanBadgeElement;
+}): BooleanElement;
 /**
  * Creates a `TimestampElement` component instance.
  *
  * @remarks
- * Formatted date and time representation.
+ * Displays an epoch timestamp using a selected date/time format. The input is a count of milliseconds, not seconds; relative formatting is interpreted by the consumer.
  *
  * @param value - The timestamp in milliseconds
+
+Unix epoch timestamp measured in milliseconds. Convert seconds-based timestamps before assigning this value.
  * @param options - Optional settings (format (defaults to `datetime`), modifiers).
  * @returns A strongly-typed `TimestampElement` object.
  */
@@ -3270,9 +4628,11 @@ export declare function timestamp(value: number, options?: {
  * Creates a `ImageReferenceElement` component instance.
  *
  * @remarks
- * Thumbnail image reference with placeholder fallback handling.
+ * References an image source for thumbnail rendering and provides accessible text and a fallback source. The client determines loading, sizing, and placeholder behavior.
  *
  * @param src - Image source URI (HTTPS URL, base64 data URI, or asset path)
+
+Source URI understood by the client renderer. Supported forms include HTTPS locations, base64 data URIs, and client asset paths; this field is not raw image bytes.
  * @param options - Optional settings (alt, aspectRatio (defaults to `1:1`), placeholder).
  * @returns A strongly-typed `ImageReferenceElement` object.
  */
@@ -3285,9 +4645,11 @@ export declare function imageReference(src: string, options?: {
  * Creates a `ImageReferenceElement` component instance.
  *
  * @remarks
- * Thumbnail image reference with placeholder fallback handling.
+ * References an image source for thumbnail rendering and provides accessible text and a fallback source. The client determines loading, sizing, and placeholder behavior.
  *
  * @param src - Image source URI (HTTPS URL, base64 data URI, or asset path)
+
+Source URI understood by the client renderer. Supported forms include HTTPS locations, base64 data URIs, and client asset paths; this field is not raw image bytes.
  * @param options - Optional settings (alt, aspectRatio (defaults to `1:1`), placeholder).
  * @returns A strongly-typed `ImageReferenceElement` object.
  */
@@ -3300,10 +4662,14 @@ export declare function imageRef(src: string, options?: {
  * Creates a `ButtonActionElement` component instance.
  *
  * @remarks
- * Interactive button action triggering an extension command.
+ * When activated, the client dispatches commandId to the specified extension and may include target and parameters as command input. disabled and variant affect presentation and availability, not the command's authorization.
  *
  * @param commandId - Command identifier to invoke
+
+Identifier of the registered extension command to dispatch when the button is activated.
  * @param label - Display label for the action
+
+User-facing label shown on the control. Keep it short and action-oriented.
  * @param options - Optional settings (extensionId, target, parameters, disabled (defaults to `false`), variant (defaults to `secondary`)).
  * @returns A strongly-typed `ButtonActionElement` object.
  */
@@ -3318,10 +4684,14 @@ export declare function buttonAction(commandId: string, label: string, options?:
  * Creates a `ExternalLinkActionElement` component instance.
  *
  * @remarks
- * External link action distinct from inline URL text values.
+ * Renders a user-invokable action that opens a destination externally. Use StringUrlElement for a link embedded in content rather than an action control.
  *
  * @param url - Target URL destination
+
+External destination opened when the user activates the link action. The client controls how external navigation is handed to the platform.
  * @param label - Display label for the action
+
+User-facing label shown on the control. Keep it short and action-oriented.
  * @returns A strongly-typed `ExternalLinkActionElement` object.
  */
 export declare function externalLinkAction(url: string, label: string): ExternalLinkActionElement;
@@ -3329,9 +4699,11 @@ export declare function externalLinkAction(url: string, label: string): External
  * Creates a `MarkdownBlockElement` component instance.
  *
  * @remarks
- * Full Markdown fallback block rendered with core typographic hierarchy, spacing, and styling.
+ * Use this custom-renderer escape hatch when the structured ViewKit elements cannot express the required rich text. Markdown rendering is a presentation fallback; prefer typed elements when consumers need to inspect individual values.
  *
  * @param content - Raw Markdown markup content
+
+Markdown source consumed by the client renderer. The schema treats it as an opaque string and does not validate the markup or its links.
  * @param options - Optional settings (modifiers).
  * @returns A strongly-typed `MarkdownBlockElement` object.
  */
@@ -3342,9 +4714,11 @@ export declare function markdownBlock(content: string, options?: {
  * Creates a `MarkdownBlockElement` component instance.
  *
  * @remarks
- * Full Markdown fallback block rendered with core typographic hierarchy, spacing, and styling.
+ * Use this custom-renderer escape hatch when the structured ViewKit elements cannot express the required rich text. Markdown rendering is a presentation fallback; prefer typed elements when consumers need to inspect individual values.
  *
  * @param content - Raw Markdown markup content
+
+Markdown source consumed by the client renderer. The schema treats it as an opaque string and does not validate the markup or its links.
  * @param options - Optional settings (modifiers).
  * @returns A strongly-typed `MarkdownBlockElement` object.
  */
@@ -3355,9 +4729,11 @@ export declare function markdown(content: string, options?: {
  * Creates a `HtmlBlockElement` component instance.
  *
  * @remarks
- * Sandboxed HTML rendering escape hatch.
+ * Use only when structured elements or Markdown cannot represent the required content. Rendering occurs in a sandboxed host context, but callers should still avoid embedding untrusted content and should not assume access to application privileges.
  *
  * @param content - Raw HTML markup content
+
+HTML source passed to the custom renderer. This is an opaque string, not a typed or sanitized DOM structure.
  * @param options - Optional settings (modifiers).
  * @returns A strongly-typed `HtmlBlockElement` object.
  */
@@ -3368,9 +4744,11 @@ export declare function htmlBlock(content: string, options?: {
  * Creates a `HtmlBlockElement` component instance.
  *
  * @remarks
- * Sandboxed HTML rendering escape hatch.
+ * Use only when structured elements or Markdown cannot represent the required content. Rendering occurs in a sandboxed host context, but callers should still avoid embedding untrusted content and should not assume access to application privileges.
  *
  * @param content - Raw HTML markup content
+
+HTML source passed to the custom renderer. This is an opaque string, not a typed or sanitized DOM structure.
  * @param options - Optional settings (modifiers).
  * @returns A strongly-typed `HtmlBlockElement` object.
  */
@@ -3381,50 +4759,57 @@ export declare function html(content: string, options?: {
  * Creates a `Slot` component instance.
  *
  * @remarks
- * Single slot within a multi-slot horizontal row layout.
+ * A slot combines an optional label, a relative width, and one visual child. Slot widths are percentages of the row and should be chosen so the full row's widths form a usable layout.
  *
  * @param content - Rendered content inside the slot
+
+One visual element displayed in this slot. Use a nested layout element when the slot itself needs multiple children.
  * @param options - Optional settings (label, width).
  * @returns A strongly-typed `Slot` object.
  */
 export declare function slot(content: UiElement, options?: {
     label?: string;
-    width?: string;
+    width?: number;
 }): Slot;
 /**
  * Creates a `MultiSlotElement` component instance.
  *
  * @remarks
- * Multi-slot horizontal row with declared column width proportions.
- * Examples: "1/3 + 2/3", "equal thirds", "1/4 + 3/4".
+ * Use this layout when a row needs explicit regions with independently controlled widths. Each slot contains one child element; unlike FlowingElement, the layout does not automatically wrap a sequence of children.
  *
  * @param slots - List of slots comprising the row
- * @param options - Optional settings (proportions).
+
+Ordered slots in the row. Each slot's width is a percentage; arrange slot definitions in the intended visual order.
  * @returns A strongly-typed `MultiSlotElement` object.
  */
-export declare function multiSlot(slots: Slot[], options?: {
-    proportions?: string;
-}): MultiSlotElement;
+export declare function multiSlot(slots: Slot[]): MultiSlotElement;
 /**
  * Creates a `FlowingElement` component instance.
  *
  * @remarks
- * Flowing inline layout container with automatic line wrapping.
- * Renders child elements horizontally in sequence, automatically wrapping to the next line when space runs out.
+ * Use for compact related values that should flow horizontally and wrap naturally at the available width. Child order is preserved; an optional separator is placed between neighboring children.
  *
  * @param elements - List of child elements rendered sequentially with line wrapping
+
+Ordered children rendered in the flow. The client wraps them as needed rather than requiring callers to calculate line breaks.
+ * @param options - Optional settings (separator).
  * @returns A strongly-typed `FlowingElement` object.
  */
-export declare function flowing(elements: UiElement[]): FlowingElement;
+export declare function flowing(elements: UiElement[], options?: {
+    separator?: Separator;
+}): FlowingElement;
 /**
  * Creates a `LabelValueElement` component instance.
  *
  * @remarks
- * Standard label and value row.
- * Displays a muted label on the left and value representation on the right with a vertical dividing line.
+ * Represents one named value with a muted left-hand label and a right-hand visual element. Use it for a single field; use TableElement for repeated rows or column-aligned data.
  *
  * @param label - Key or descriptive label displayed muted on the left
+
+Human-readable name for the value. This text is rendered as the row label rather than as a separate UiElement.
  * @param value - Rendered value element on the right
+
+Value content rendered in the right-hand region. It may be a primitive or a nested structural element.
  * @param options - Optional settings (withDivider (defaults to `false`)).
  * @returns A strongly-typed `LabelValueElement` object.
  */
@@ -3435,23 +4820,26 @@ export declare function labelValue(label: string, value: UiElement, options?: {
  * Creates a `TableColumn` component instance.
  *
  * @remarks
- * Column definition for structured tables.
+ * Describes one table column and its visual sizing. When columns are supplied, their order corresponds to the position of each cell in a row.
  *
- * @param options - Optional settings (header, align (defaults to `left`), width).
+ * @param options - Optional settings (header, align (defaults to `left`), width, widthMode (defaults to `fixed`)).
  * @returns A strongly-typed `TableColumn` object.
  */
 export declare function tableColumn(options?: {
     header?: string;
     align?: TableColumnAlign;
-    width?: string;
+    width?: number;
+    widthMode?: TableColumnWidthMode;
 }): TableColumn;
 /**
  * Creates a `TableRow` component instance.
  *
  * @remarks
- * Single table row containing an array of cell values.
+ * A row's cell array is positional: cell at each index corresponds to the column at that index. Keep row lengths aligned with the table's explicit column definitions when present.
  *
  * @param cells - Array of cell values corresponding to table columns
+
+Ordered contents for this row. Each cell is a UiElement so values can use the same primitive and layout renderers as other ViewKit content.
  * @returns A strongly-typed `TableRow` object.
  */
 export declare function tableRow(cells: UiElement[]): TableRow;
@@ -3459,15 +4847,15 @@ export declare function tableRow(cells: UiElement[]): TableRow;
  * Creates a `TableElement` component instance.
  *
  * @remarks
- * Structured tabular data representation.
- * Supports header/borderless modes, 2-column key-value tables, and 3-column data tables.
+ * Use for data that benefits from aligned rows and columns, including key/value and multi-column tables. Supply rows in display order; explicit columns are optional, and divider/striping flags independently control visual separators and alternating backgrounds.
  *
  * @param rows - Tabular data rows
- * @param options - Optional settings (hasHeader (defaults to `true`), isStriped (defaults to `false`), withColumnSeparators (defaults to `false`), withRowSeparators (defaults to `false`), columns).
+
+Ordered table rows. Each row's cells correspond positionally to the declared columns.
+ * @param options - Optional settings (isStriped (defaults to `false`), withColumnSeparators (defaults to `false`), withRowSeparators (defaults to `false`), columns).
  * @returns A strongly-typed `TableElement` object.
  */
 export declare function table(rows: TableRow[], options?: {
-    hasHeader?: boolean;
     isStriped?: boolean;
     withColumnSeparators?: boolean;
     withRowSeparators?: boolean;
@@ -3477,9 +4865,11 @@ export declare function table(rows: TableRow[], options?: {
  * Creates a `RepeatingGroupEntry` component instance.
  *
  * @remarks
- * Single entry within a repeating group.
+ * A repeating entry carries a stable display label and either one primary value or a list of nested elements, depending on the shape needed by the feature.
  *
  * @param label - Entry label
+
+Short label identifying this entry within the repeated group.
  * @param options - Optional settings (value, elements).
  * @returns A strongly-typed `RepeatingGroupEntry` object.
  */
@@ -3491,9 +4881,11 @@ export declare function repeatingGroupEntry(label: string, options?: {
  * Creates a `RepeatingGroupElement` component instance.
  *
  * @remarks
- * Repeating group container where entries share uniform structure and retain per-entry labels.
+ * Groups a sequence of labeled entries under one optional section title. Use it when records have the same general presentation but need their own labels.
  *
  * @param entries - List of repeated entry records
+
+Entries in display order. Each entry supplies its own label and content.
  * @param options - Optional settings (title).
  * @returns A strongly-typed `RepeatingGroupElement` object.
  */
@@ -3504,10 +4896,14 @@ export declare function repeatingGroup(entries: RepeatingGroupEntry[], options?:
  * Creates a `CollapsibleGroupElement` component instance.
  *
  * @remarks
- * Collapsible disclosure container (accordion) with summary badge.
+ * Groups nested content behind a disclosure control. The title names the group, summary can provide a compact status indicator, and defaultExpanded controls only the initial state.
  *
  * @param title - Group title (e.g. "Show specimen details")
+
+Text shown on the disclosure control. Use a concise action or section name that remains meaningful while the content is collapsed.
  * @param elements - Nested content elements revealed when expanded
+
+Ordered child elements made visible by expanding the group.
  * @param options - Optional settings (summary, defaultExpanded (defaults to `false`)).
  * @returns A strongly-typed `CollapsibleGroupElement` object.
  */
@@ -3519,7 +4915,7 @@ export declare function collapsibleGroup(title: string, elements: UiElement[], o
  * Creates a `DividerElement` component instance.
  *
  * @remarks
- * Visual hairline separator separating sections or element groups.
+ * A standalone visual separator for dividing adjacent sections or element groups. Use the divider flags on tables or rows when the separator is part of that structure.
  *
  * @param options - Optional settings (style (defaults to `hairline`)).
  * @returns A strongly-typed `DividerElement` object.
@@ -3531,7 +4927,7 @@ export declare function divider(options?: {
  * Creates a `Envelop` component instance.
  *
  * @remarks
- * Base envelope container model holding the schema version attribute.
+ * All root ViewKit documents extend this envelope so consumers can identify the schema contract version before processing the root content.
  *
  * @param options - Optional settings (schemaVersion (defaults to `1.0`)).
  * @returns A strongly-typed `Envelop` object.
@@ -3612,21 +5008,21 @@ export declare function isEnvelop(value: unknown, withDeepValidation?: boolean):
  */
 export declare function isUiElement(value: unknown, withDeepValidation?: boolean): value is UiElement;
 /**
- * Type guard predicate narrowing a value to `StringShortElement`.
+ * Type guard predicate narrowing a value to `StringElement`.
  *
  * @param value - The value to inspect.
  * @param withDeepValidation - Whether to recursively validate all properties.
- * @returns `true` if the value is a `StringShortElement` (type = "string-short"), otherwise `false`.
+ * @returns `true` if the value is a `StringElement` (type = "string"), otherwise `false`.
  */
-export declare function isStringShortElement(value: unknown, withDeepValidation?: boolean): value is StringShortElement;
+export declare function isStringElement(value: unknown, withDeepValidation?: boolean): value is StringElement;
 /**
- * Type guard predicate narrowing a value to `StringLongElement`.
+ * Type guard predicate narrowing a value to `StringsElement`.
  *
  * @param value - The value to inspect.
  * @param withDeepValidation - Whether to recursively validate all properties.
- * @returns `true` if the value is a `StringLongElement` (type = "string-long"), otherwise `false`.
+ * @returns `true` if the value is a `StringsElement` (type = "strings"), otherwise `false`.
  */
-export declare function isStringLongElement(value: unknown, withDeepValidation?: boolean): value is StringLongElement;
+export declare function isStringsElement(value: unknown, withDeepValidation?: boolean): value is StringsElement;
 /**
  * Type guard predicate narrowing a value to `StringCodeElement`.
  *
@@ -3675,6 +5071,14 @@ export declare function isIdentifierElement(value: unknown, withDeepValidation?:
  * @returns `true` if the value is a `RatioElement` (type = "ratio"), otherwise `false`.
  */
 export declare function isRatioElement(value: unknown, withDeepValidation?: boolean): value is RatioElement;
+/**
+ * Type guard predicate narrowing a value to `DimensionsElement`.
+ *
+ * @param value - The value to inspect.
+ * @param withDeepValidation - Whether to recursively validate all properties.
+ * @returns `true` if the value is a `DimensionsElement` (type = "dimensions"), otherwise `false`.
+ */
+export declare function isDimensionsElement(value: unknown, withDeepValidation?: boolean): value is DimensionsElement;
 /**
  * Type guard predicate narrowing a value to `ColourElement`.
  *
@@ -3708,21 +5112,13 @@ export declare function isNumberBoundedStarsElement(value: unknown, withDeepVali
  */
 export declare function isNumberBoundedMeterElement(value: unknown, withDeepValidation?: boolean): value is NumberBoundedMeterElement;
 /**
- * Type guard predicate narrowing a value to `BooleanPlainElement`.
- *
- * @param value - The value to inspect.
- * @param withDeepValidation - Whether to recursively validate all properties.
- * @returns `true` if the value is a `BooleanPlainElement` (type = "boolean-plain"), otherwise `false`.
- */
-export declare function isBooleanPlainElement(value: unknown, withDeepValidation?: boolean): value is BooleanPlainElement;
-/**
- * Type guard predicate narrowing a value to `BooleanBadgeElement`.
+ * Type guard predicate narrowing a value to `BooleanElement`.
  *
  * @param value - The value to inspect.
  * @param withDeepValidation - Whether to recursively validate all properties.
- * @returns `true` if the value is a `BooleanBadgeElement` (type = "boolean-badge"), otherwise `false`.
+ * @returns `true` if the value is a `BooleanElement` (type = "boolean"), otherwise `false`.
  */
-export declare function isBooleanBadgeElement(value: unknown, withDeepValidation?: boolean): value is BooleanBadgeElement;
+export declare function isBooleanElement(value: unknown, withDeepValidation?: boolean): value is BooleanElement;
 /**
  * Type guard predicate narrowing a value to `TimestampElement`.
  *