@picteus/extension-sdk 0.17.0 → 0.19.0

package/dist/generated/viewKit.js

@@ -1,5 +1,5 @@
 // ---------------------------------------------------------------------------
-// Auto-generated by @picteus/specification-factory emitter. Do not edit directly.
+// Auto-generated by @picteus/specification-factory. Do not edit directly.
 // ---------------------------------------------------------------------------
 /** Generic base class providing recursive JSON serialization for all model instances. */
 export class ViewKitNode {
@@ -41,113 +41,162 @@ export class ViewKitNode {
 /** Typographic stroke weight styling. */
 export var TextWeight;
 (function (TextWeight) {
-    // Thin / light text weight
+    /** Thin / light text weight */
     TextWeight["thin"] = "thin";
-    // Standard text weight
+    /** Standard text weight */
     TextWeight["normal"] = "normal";
-    // Heavy / bold text weight
+    /** Heavy / bold text weight */
     TextWeight["heavy"] = "heavy";
 })(TextWeight || (TextWeight = {}));
 /** Visual text color intensity and contrast. */
 export var TextIntensity;
 (function (TextIntensity) {
-    // Low visual contrast / subdued text color
+    /** Low visual contrast / subdued text color */
     TextIntensity["low"] = "low";
-    // Standard text color
+    /** Standard text color */
     TextIntensity["medium"] = "medium";
-    // High visual contrast / intense text color
+    /** High visual contrast / intense text color */
     TextIntensity["high"] = "high";
 })(TextIntensity || (TextIntensity = {}));
 /** Geometric shape representation for visual containers and indicators. */
 export var Shape;
 (function (Shape) {
-    // Circular container shape
+    /** Circular container shape */
     Shape["circle"] = "circle";
-    // Square container shape
+    /** Square container shape */
     Shape["square"] = "square";
 })(Shape || (Shape = {}));
 /** Relative sizing scale for visual elements and indicators. */
 export var Size;
 (function (Size) {
-    // Compact small size
+    /** Compact small size */
     Size["small"] = "small";
-    // Standard medium size
+    /** Standard medium size */
     Size["medium"] = "medium";
-    // Prominent large size
+    /** Prominent large size */
     Size["large"] = "large";
 })(Size || (Size = {}));
-/** Representation style for short string values. */
-export var StringShortRepresentation;
-(function (StringShortRepresentation) {
-    // Standard plain text rendering
-    StringShortRepresentation["plain"] = "plain";
-    // Visual chip / tag pill representation
-    StringShortRepresentation["chip"] = "chip";
-})(StringShortRepresentation || (StringShortRepresentation = {}));
+/** Visual presentation style for string values. */
+export var StringRepresentation;
+(function (StringRepresentation) {
+    /** Standard inline text rendering */
+    StringRepresentation["plain"] = "plain";
+    /** Visual chip / tag pill representation */
+    StringRepresentation["chip"] = "chip";
+    /** Multiline text with preserved whitespace and line breaks */
+    StringRepresentation["multiline"] = "multiline";
+})(StringRepresentation || (StringRepresentation = {}));
+/** Visual separator rendered between sequential elements or items. */
+export var Separator;
+(function (Separator) {
+    /** Vertical dividing bar */
+    Separator["bar"] = "bar";
+    /** Comma separator */
+    Separator["comma"] = "comma";
+    /** Bullet dot separator */
+    Separator["dot"] = "dot";
+    /** Forward slash separator */
+    Separator["slash"] = "slash";
+    /** Dash separator */
+    Separator["dash"] = "dash";
+    /** Space separator */
+    Separator["space"] = "space";
+})(Separator || (Separator = {}));
 /** Supported syntax highlighting languages for formatted code blocks. */
 export var CodeLanguage;
 (function (CodeLanguage) {
-    // XML markup syntax
+    /** XML markup syntax */
     CodeLanguage["xml"] = "xml";
-    // JSON format syntax
+    /** JSON format syntax */
     CodeLanguage["json"] = "json";
-    // YAML format syntax
+    /** YAML format syntax */
     CodeLanguage["yaml"] = "yaml";
 })(CodeLanguage || (CodeLanguage = {}));
+/** Visual presentation style for boolean values. */
+export var BooleanRepresentation;
+(function (BooleanRepresentation) {
+    /** Standard inline text rendering (e.g. "true" / "false" or custom labels) */
+    BooleanRepresentation["plain"] = "plain";
+    /** Visual badge pill representation */
+    BooleanRepresentation["badge"] = "badge";
+})(BooleanRepresentation || (BooleanRepresentation = {}));
 /** Visual color tone variants for badge pill representations. */
 export var BadgeVariant;
 (function (BadgeVariant) {
-    // Neutral gray tone
+    /** Neutral gray tone */
     BadgeVariant["neutral"] = "neutral";
-    // Success green tone
+    /** Success green tone */
     BadgeVariant["success"] = "success";
-    // Warning yellow/orange tone
+    /** Warning yellow/orange tone */
     BadgeVariant["warning"] = "warning";
-    // Danger red tone
+    /** Danger red tone */
     BadgeVariant["danger"] = "danger";
 })(BadgeVariant || (BadgeVariant = {}));
 /** Presentation format styles for timestamp elements. */
 export var TimestampFormat;
 (function (TimestampFormat) {
-    // Complete date and time display
+    /** Complete date and time display */
     TimestampFormat["datetime"] = "datetime";
-    // Date-only display
+    /** Date-only display */
     TimestampFormat["date"] = "date";
-    // Time-only display
+    /** Time-only display */
     TimestampFormat["time"] = "time";
-    // Relative time expression (e.g. "5 minutes ago")
+    /** Relative time expression (e.g. "5 minutes ago") */
     TimestampFormat["relative"] = "relative";
 })(TimestampFormat || (TimestampFormat = {}));
 /** Visual style variants for interactive button actions. */
 export var ButtonVariant;
 (function (ButtonVariant) {
-    // Primary emphasis button style for default/recommended actions
+    /** Primary emphasis button style for default/recommended actions */
     ButtonVariant["primary"] = "primary";
-    // Secondary standard button style
+    /** Secondary standard button style */
     ButtonVariant["secondary"] = "secondary";
-    // Subtle low-contrast button style
+    /** Subtle low-contrast button style */
     ButtonVariant["subtle"] = "subtle";
-    // Destructive / dangerous action button style
+    /** Destructive / dangerous action button style */
     ButtonVariant["danger"] = "danger";
 })(ButtonVariant || (ButtonVariant = {}));
-/** 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 var TableColumnAlign;
 (function (TableColumnAlign) {
-    // Left-aligned text
+    /** Left-aligned text */
     TableColumnAlign["left"] = "left";
-    // Center-aligned text
+    /** Center-aligned text */
     TableColumnAlign["center"] = "center";
-    // Right-aligned text
+    /** Right-aligned text */
     TableColumnAlign["right"] = "right";
 })(TableColumnAlign || (TableColumnAlign = {}));
-/** 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 var TableColumnWidthMode;
+(function (TableColumnWidthMode) {
+    /** Fixed width constraint */
+    TableColumnWidthMode["fixed"] = "fixed";
+    /** Maximum width upper bound constraint */
+    TableColumnWidthMode["maximum"] = "maximum";
+})(TableColumnWidthMode || (TableColumnWidthMode = {}));
+/**
+ * Visual styling variants for hairline dividers.
+ *
+ * @remarks
+ * Selects the visual stroke treatment used by DividerElement.
+ */
 export var DividerStyle;
 (function (DividerStyle) {
-    // Subtle thin hairline border
+    /** Subtle thin hairline border */
     DividerStyle["hairline"] = "hairline";
-    // Solid standard divider line
+    /** Solid standard divider line */
     DividerStyle["solid"] = "solid";
-    // Dashed separator line
+    /** Dashed separator line */
     DividerStyle["dashed"] = "dashed";
 })(DividerStyle || (DividerStyle = {}));
 /** Abstract base class for all `UiElement` models. */
@@ -161,14 +210,22 @@ export class BaseUiAction extends ViewKitNode {
  * 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 class TruncateOptionsClass extends ViewKitNode {
-    /** 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.
+     */
     characterLimit;
     /**
      * 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
      */
     showMore;
@@ -176,6 +233,8 @@ export class TruncateOptionsClass extends ViewKitNode {
      * 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, options) {
@@ -188,10 +247,15 @@ export class TruncateOptionsClass extends ViewKitNode {
  * 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 class BaseModifiersClass extends ViewKitNode {
-    /** 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.
+     */
     copyable;
     /**
      * Constructs a new `BaseModifiersClass` instance.
@@ -207,30 +271,49 @@ export class BaseModifiersClass extends ViewKitNode {
  * 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 class PrimitiveModifiersClass extends ViewKitNode {
-    /** 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.
+     */
     truncate;
     /**
      * Typographic text weight
      *
+     * @remarks
+     * Relative font weight for textual rendering; defaults to normal.
+     *
      * @defaultValue TextWeight.normal
      */
     weight;
     /**
      * Visual text color intensity
      *
+     * @remarks
+     * Relative contrast treatment for the text; defaults to medium.
+     *
      * @defaultValue TextIntensity.medium
      */
     intensity;
     /**
      * 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
      */
     monospace;
-    /** 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.
+     */
     copyable;
     /**
      * Constructs a new `PrimitiveModifiersClass` instance.
@@ -247,68 +330,102 @@ export class PrimitiveModifiersClass extends ViewKitNode {
     }
 }
 /**
- * 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 class StringShortElementClass extends BaseUiElement {
+export class StringElementClass extends BaseUiElement {
     /**
-     * Discriminator identifier for `StringShortElement`.
+     * Discriminator identifier for `StringElement`.
      *
-     * @defaultValue "string-short"
+     * @defaultValue "string"
+     */
+    type = "string";
+    /**
+     * Text value
+     *
+     * @remarks
+     * Text to render. Supply plain text; this field is not a Markdown or HTML document.
      */
-    type = "string-short";
-    /** Text value */
     value;
     /**
      * 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
      */
     representation;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     modifiers;
     /**
-     * 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, options) {
         super();
         this.value = value;
-        this.representation = options?.representation ?? StringShortRepresentation.plain;
+        this.representation = options?.representation ?? StringRepresentation.plain;
         this.modifiers = options?.modifiers;
     }
 }
 /**
- * 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 class StringLongElementClass extends BaseUiElement {
+export class StringsElementClass extends BaseUiElement {
     /**
-     * Discriminator identifier for `StringLongElement`.
+     * Discriminator identifier for `StringsElement`.
      *
-     * @defaultValue "string-long"
+     * @defaultValue "strings"
      */
-    type = "string-long";
-    /** Text value */
-    value;
+    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.
+     */
+    values;
+    /**
+     * 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
+     */
+    representation;
+    /**
+     * Optional visual separator rendered between sequential values
+     *
+     * @remarks
+     * Separator inserted between adjacent values in plain representation. It does not become part of any value.
+     */
+    separator;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     modifiers;
     /**
-     * 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, options) {
+    constructor(values, options) {
         super();
-        this.value = value;
+        this.values = values ? [...values] : [];
+        this.representation = options?.representation ?? StringRepresentation.plain;
+        this.separator = options?.separator;
         this.modifiers = options?.modifiers;
     }
 }
@@ -316,7 +433,7 @@ export class StringLongElementClass extends BaseUiElement {
  * 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 class StringCodeElementClass extends BaseUiElement {
     /**
@@ -325,9 +442,19 @@ export class StringCodeElementClass extends BaseUiElement {
      * @defaultValue "string-code"
      */
     type = "string-code";
-    /** Text value */
+    /**
+     * Text value
+     *
+     * @remarks
+     * Code or text snippet to display. Include any desired line breaks in this string.
+     */
     value;
-    /** 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.
+     */
     language;
     /** Optional visual modifiers (copyable) */
     modifiers;
@@ -335,6 +462,8 @@ export class StringCodeElementClass extends BaseUiElement {
      * 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, options) {
@@ -348,7 +477,7 @@ export class StringCodeElementClass extends BaseUiElement {
  * 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 class XmlElementClass extends BaseUiElement {
     /**
@@ -357,7 +486,12 @@ export class XmlElementClass extends BaseUiElement {
      * @defaultValue "xml"
      */
     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.
+     */
     value;
     /** Optional visual modifiers (copyable) */
     modifiers;
@@ -365,6 +499,8 @@ export class XmlElementClass extends BaseUiElement {
      * 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, options) {
@@ -377,7 +513,7 @@ export class XmlElementClass extends BaseUiElement {
  * 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 class JsonElementClass extends BaseUiElement {
     /**
@@ -386,7 +522,12 @@ export class JsonElementClass extends BaseUiElement {
      * @defaultValue "json"
      */
     type = "json";
-    /** JSON content value */
+    /**
+     * JSON content value
+     *
+     * @remarks
+     * Serialized JSON text to render. No parsing or schema validation is implied by this element.
+     */
     value;
     /** Optional visual modifiers (copyable) */
     modifiers;
@@ -394,6 +535,8 @@ export class JsonElementClass extends BaseUiElement {
      * 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, options) {
@@ -406,7 +549,7 @@ export class JsonElementClass extends BaseUiElement {
  * 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 class StringUrlElementClass extends BaseUiElement {
     /**
@@ -415,7 +558,12 @@ export class StringUrlElementClass extends BaseUiElement {
      * @defaultValue "string-url"
      */
     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.
+     */
     value;
     /** Optional custom anchor text label */
     label;
@@ -425,6 +573,8 @@ export class StringUrlElementClass extends BaseUiElement {
      * 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, options) {
@@ -438,7 +588,7 @@ export class StringUrlElementClass extends BaseUiElement {
  * 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 class IdentifierElementClass extends BaseUiElement {
     /**
@@ -447,7 +597,12 @@ export class IdentifierElementClass extends BaseUiElement {
      * @defaultValue "identifier"
      */
     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.
+     */
     value;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     modifiers;
@@ -455,6 +610,8 @@ export class IdentifierElementClass extends BaseUiElement {
      * 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, options) {
@@ -467,7 +624,7 @@ export class IdentifierElementClass extends BaseUiElement {
  * 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 class RatioElementClass extends BaseUiElement {
     /**
@@ -476,7 +633,12 @@ export class RatioElementClass extends BaseUiElement {
      * @defaultValue "ratio"
      */
     type = "ratio";
-    /** Aspect ratio numerical expression */
+    /**
+     * Aspect ratio numerical expression
+     *
+     * @remarks
+     * Numeric ratio value used by the renderer to produce an aspect-ratio display.
+     */
     value;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     modifiers;
@@ -484,6 +646,8 @@ export class RatioElementClass extends BaseUiElement {
      * 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, options) {
@@ -492,11 +656,58 @@ export class RatioElementClass extends BaseUiElement {
         this.modifiers = options?.modifiers;
     }
 }
+/**
+ * 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 class DimensionsElementClass extends BaseUiElement {
+    /**
+     * Discriminator identifier for `DimensionsElement`.
+     *
+     * @defaultValue "dimensions"
+     */
+    type = "dimensions";
+    /**
+     * Width in pixels
+     *
+     * @remarks
+     * Horizontal pixel count. Values below one are rejected by the schema constraint.
+     */
+    width;
+    /**
+     * Height in pixels
+     *
+     * @remarks
+     * Vertical pixel count. Values below one are rejected by the schema constraint.
+     */
+    height;
+    /** Optional visual modifiers (copyable) */
+    modifiers;
+    /**
+     * 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, height, options) {
+        super();
+        this.width = width;
+        this.height = height;
+        this.modifiers = options?.modifiers;
+    }
+}
 /**
  * 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 class ColourElementClass extends BaseUiElement {
     /**
@@ -505,25 +716,44 @@ export class ColourElementClass extends BaseUiElement {
      * @defaultValue "color"
      */
     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.
+     */
     value;
-    /** Optional descriptive color name label */
+    /**
+     * Optional descriptive color name label
+     *
+     * @remarks
+     * Human-readable color name available to the renderer when text is shown.
+     */
     label;
     /**
      * 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
      */
     showText;
     /**
      * Visual shape of the color indicator
      *
+     * @remarks
+     * Geometry used for the swatch; defaults to a circle.
+     *
      * @defaultValue Shape.circle
      */
     shape;
     /**
      * Visual size of the color indicator
      *
+     * @remarks
+     * Relative size class for the swatch; defaults to medium.
+     *
      * @defaultValue Size.medium
      */
     size;
@@ -533,6 +763,8 @@ export class ColourElementClass extends BaseUiElement {
      * 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, options) {
@@ -549,7 +781,7 @@ export class ColourElementClass extends BaseUiElement {
  * 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 class NumberUnboundedElementClass extends BaseUiElement {
     /**
@@ -558,9 +790,19 @@ export class NumberUnboundedElementClass extends BaseUiElement {
      * @defaultValue "number-unbounded"
      */
     type = "number-unbounded";
-    /** Numeric value */
+    /**
+     * Numeric value
+     *
+     * @remarks
+     * Number to display. Its meaning and any valid range are defined by the producing feature.
+     */
     value;
-    /** 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.
+     */
     unit;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     modifiers;
@@ -568,6 +810,8 @@ export class NumberUnboundedElementClass extends BaseUiElement {
      * 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, options) {
@@ -581,7 +825,7 @@ export class NumberUnboundedElementClass extends BaseUiElement {
  * 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 class NumberBoundedStarsElementClass extends BaseUiElement {
     /**
@@ -590,9 +834,19 @@ export class NumberBoundedStarsElementClass extends BaseUiElement {
      * @defaultValue "number-stars"
      */
     type = "number-stars";
-    /** Numeric rating score */
+    /**
+     * Numeric rating score
+     *
+     * @remarks
+     * Score represented by the filled portion of the star display.
+     */
     value;
-    /** 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.
+     */
     maximum;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     modifiers;
@@ -600,6 +854,8 @@ export class NumberBoundedStarsElementClass extends BaseUiElement {
      * 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, options) {
@@ -613,7 +869,7 @@ export class NumberBoundedStarsElementClass extends BaseUiElement {
  * 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 class NumberBoundedMeterElementClass extends BaseUiElement {
     /**
@@ -622,15 +878,40 @@ export class NumberBoundedMeterElementClass extends BaseUiElement {
      * @defaultValue "number-meter"
      */
     type = "number-meter";
-    /** Numeric value */
+    /**
+     * Numeric value
+     *
+     * @remarks
+     * Current measurement or score represented by the meter.
+     */
     value;
-    /** Minimum scale bound (defaults to 0) */
+    /**
+     * Minimum scale bound (defaults to 0)
+     *
+     * @remarks
+     * Lower end of the meter range. Defaults to zero when omitted.
+     */
     minimum;
-    /** 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.
+     */
     maximum;
-    /** 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.
+     */
     label;
-    /** 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.
+     */
     unit;
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     modifiers;
@@ -638,6 +919,8 @@ export class NumberBoundedMeterElementClass extends BaseUiElement {
      * 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, options) {
@@ -651,63 +934,57 @@ export class NumberBoundedMeterElementClass extends BaseUiElement {
     }
 }
 /**
- * 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 class BooleanPlainElementClass extends BaseUiElement {
+export class BooleanElementClass extends BaseUiElement {
     /**
-     * Discriminator identifier for `BooleanPlainElement`.
+     * Discriminator identifier for `BooleanElement`.
      *
-     * @defaultValue "boolean-plain"
+     * @defaultValue "boolean"
      */
-    type = "boolean-plain";
-    /** Boolean state value */
-    value;
-    /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
-    modifiers;
+    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, options) {
-        super();
-        this.value = value;
-        this.modifiers = options?.modifiers;
-    }
-}
-/**
- * Class implementation of the `BooleanBadgeElement` interface.
- *
- * @remarks
- * Visual badge pill representation of a boolean state.
- */
-export class BooleanBadgeElementClass extends BaseUiElement {
+    value;
     /**
-     * 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
      */
-    type = "boolean-badge";
-    /** Boolean state value */
-    value;
+    representation;
     /**
      * 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"
      */
     trueLabel;
     /**
      * 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"
      */
     falseLabel;
     /**
-     * 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
      */
@@ -715,14 +992,17 @@ export class BooleanBadgeElementClass extends BaseUiElement {
     /** Optional visual modifiers (copyable, truncate, emphasis, monospace) */
     modifiers;
     /**
-     * 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, options) {
         super();
         this.value = value;
+        this.representation = options?.representation ?? BooleanRepresentation.plain;
         this.trueLabel = options?.trueLabel ?? "true";
         this.falseLabel = options?.falseLabel ?? "false";
         this.variant = options?.variant ?? BadgeVariant.neutral;
@@ -733,7 +1013,7 @@ export class BooleanBadgeElementClass extends BaseUiElement {
  * 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 class TimestampElementClass extends BaseUiElement {
     /**
@@ -742,11 +1022,19 @@ export class TimestampElementClass extends BaseUiElement {
      * @defaultValue "timestamp"
      */
     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.
+     */
     value;
     /**
      * 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
      */
     format;
@@ -756,6 +1044,8 @@ export class TimestampElementClass extends BaseUiElement {
      * 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, options) {
@@ -769,7 +1059,7 @@ export class TimestampElementClass extends BaseUiElement {
  * 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 class ImageReferenceElementClass extends BaseUiElement {
     /**
@@ -778,22 +1068,42 @@ export class ImageReferenceElementClass extends BaseUiElement {
      * @defaultValue "image-ref"
      */
     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.
+     */
     src;
-    /** 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.
+     */
     alt;
     /**
      * 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"
      */
     aspectRatio;
-    /** 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.
+     */
     placeholder;
     /**
      * 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, options) {
@@ -808,7 +1118,7 @@ export class ImageReferenceElementClass extends BaseUiElement {
  * 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 class ButtonActionElementClass extends BaseUiAction {
     /**
@@ -817,25 +1127,56 @@ export class ButtonActionElementClass extends BaseUiAction {
      * @defaultValue "button"
      */
     type = "button";
-    /** Command identifier to invoke */
+    /**
+     * Command identifier to invoke
+     *
+     * @remarks
+     * Identifier of the registered extension command to dispatch when the button is activated.
+     */
     commandId;
-    /** Display label for the action */
+    /**
+     * Display label for the action
+     *
+     * @remarks
+     * User-facing label shown on the control. Keep it short and action-oriented.
+     */
     label;
-    /** 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.
+     */
     extensionId;
-    /** 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.
+     */
     target;
-    /** 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.
+     */
     parameters;
     /**
      * 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
      */
     disabled;
     /**
      * 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
      */
     variant;
@@ -843,7 +1184,11 @@ export class ButtonActionElementClass extends BaseUiAction {
      * 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, label, options) {
@@ -861,7 +1206,7 @@ export class ButtonActionElementClass extends BaseUiAction {
  * 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 class ExternalLinkActionElementClass extends BaseUiAction {
     /**
@@ -870,15 +1215,29 @@ export class ExternalLinkActionElementClass extends BaseUiAction {
      * @defaultValue "external-link"
      */
     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.
+     */
     url;
-    /** Display label for the action */
+    /**
+     * Display label for the action
+     *
+     * @remarks
+     * User-facing label shown on the control. Keep it short and action-oriented.
+     */
     label;
     /**
      * 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, label) {
         super();
@@ -890,7 +1249,7 @@ export class ExternalLinkActionElementClass extends BaseUiAction {
  * 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 class MarkdownBlockElementClass extends BaseUiElement {
     /**
@@ -899,7 +1258,12 @@ export class MarkdownBlockElementClass extends BaseUiElement {
      * @defaultValue "markdown"
      */
     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.
+     */
     content;
     /** Optional visual modifiers (copyable) */
     modifiers;
@@ -907,6 +1271,8 @@ export class MarkdownBlockElementClass extends BaseUiElement {
      * 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, options) {
@@ -919,7 +1285,7 @@ export class MarkdownBlockElementClass extends BaseUiElement {
  * 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 class HtmlBlockElementClass extends BaseUiElement {
     /**
@@ -928,7 +1294,12 @@ export class HtmlBlockElementClass extends BaseUiElement {
      * @defaultValue "html"
      */
     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.
+     */
     content;
     /** Optional visual modifiers (copyable) */
     modifiers;
@@ -936,6 +1307,8 @@ export class HtmlBlockElementClass extends BaseUiElement {
      * 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, options) {
@@ -948,19 +1321,36 @@ export class HtmlBlockElementClass extends BaseUiElement {
  * 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 class SlotClass extends ViewKitNode {
-    /** 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.
+     */
     content;
-    /** 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.
+     */
     label;
-    /** Relative or fractional width proportion (e.g. "1/3", "2/3", "100px", "auto") */
+    /**
+     * Width percentage (1-100)
+     *
+     * @remarks
+     * Relative share of the row width. The schema constrains explicit values to the inclusive range 1 through 100.
+     */
     width;
     /**
      * 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, options) {
@@ -974,8 +1364,7 @@ export class SlotClass extends ViewKitNode {
  * 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 class MultiSlotElementClass extends BaseUiElement {
     /**
@@ -984,28 +1373,30 @@ export class MultiSlotElementClass extends BaseUiElement {
      * @defaultValue "multi-slot"
      */
     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.
+     */
     slots;
-    /** Proportions descriptor (e.g. "1/3 + 2/3", "equal", "1/4 + 3/4") */
-    proportions;
     /**
      * 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, options) {
+    constructor(slots) {
         super();
         this.slots = slots ? [...slots] : [];
-        this.proportions = options?.proportions;
     }
 }
 /**
  * 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 class FlowingElementClass extends BaseUiElement {
     /**
@@ -1014,24 +1405,39 @@ export class FlowingElementClass extends BaseUiElement {
      * @defaultValue "flowing"
      */
     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.
+     */
     elements;
+    /**
+     * 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.
+     */
+    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) {
+    constructor(elements, options) {
         super();
         this.elements = elements ? [...elements] : [];
+        this.separator = options?.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 class LabelValueElementClass extends BaseUiElement {
     /**
@@ -1040,13 +1446,26 @@ export class LabelValueElementClass extends BaseUiElement {
      * @defaultValue "label-value"
      */
     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.
+     */
     label;
-    /** 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.
+     */
     value;
     /**
      * Whether to render a bottom border/hairline divider
      *
+     * @remarks
+     * Enables a horizontal separator beneath this row when true. Defaults to false.
+     *
      * @defaultValue false
      */
     withDivider;
@@ -1054,7 +1473,11 @@ export class LabelValueElementClass extends BaseUiElement {
      * 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, value, options) {
@@ -1068,44 +1491,74 @@ export class LabelValueElementClass extends BaseUiElement {
  * 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 class TableColumnClass extends ViewKitNode {
-    /** Display header text */
+    /**
+     * Display header text
+     *
+     * @remarks
+     * Optional header shown above values in this column. Omit when the table has no header row.
+     */
     header;
     /**
      * Text horizontal alignment
      *
+     * @remarks
+     * Horizontal alignment applied to cell content in the column. Defaults to left.
+     *
      * @defaultValue TableColumnAlign.left
      */
     align;
-    /** Optional width constraint */
+    /**
+     * Width percentage (1-100)
+     *
+     * @remarks
+     * Column width percentage used with widthMode. Explicit values are constrained to 1 through 100.
+     */
     width;
+    /**
+     * 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
+     */
+    widthMode;
     /**
      * 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) {
         super();
         this.header = options?.header;
         this.align = options?.align ?? TableColumnAlign.left;
         this.width = options?.width;
+        this.widthMode = options?.widthMode ?? TableColumnWidthMode.fixed;
     }
 }
 /**
  * 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 class TableRowClass extends ViewKitNode {
-    /** 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.
+     */
     cells;
     /**
      * 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) {
         super();
@@ -1116,8 +1569,7 @@ export class TableRowClass extends ViewKitNode {
  * 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 class TableElementClass extends BaseUiElement {
     /**
@@ -1126,44 +1578,58 @@ export class TableElementClass extends BaseUiElement {
      * @defaultValue "table"
      */
     type = "table";
-    /** Tabular data rows */
-    rows;
     /**
-     * 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.
      */
-    hasHeader;
+    rows;
     /**
      * Whether to render alternating row background colors
      *
+     * @remarks
+     * Enables alternating backgrounds across successive rows to improve scanability. Defaults to false.
+     *
      * @defaultValue false
      */
     isStriped;
     /**
      * Whether to render vertical column separators
      *
+     * @remarks
+     * Adds vertical dividers between columns when true. Defaults to false.
+     *
      * @defaultValue false
      */
     withColumnSeparators;
     /**
      * Whether to render horizontal row separators
      *
+     * @remarks
+     * Adds horizontal dividers between rows when true. Defaults to false.
+     *
      * @defaultValue false
      */
     withRowSeparators;
-    /** 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.
+     */
     columns;
     /**
      * 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, options) {
         super();
         this.rows = rows ? [...rows] : [];
-        this.hasHeader = options?.hasHeader ?? true;
         this.isStriped = options?.isStriped ?? false;
         this.withColumnSeparators = options?.withColumnSeparators ?? false;
         this.withRowSeparators = options?.withRowSeparators ?? false;
@@ -1174,19 +1640,36 @@ export class TableElementClass extends BaseUiElement {
  * 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 class RepeatingGroupEntryClass extends ViewKitNode {
-    /** Entry label */
+    /**
+     * Entry label
+     *
+     * @remarks
+     * Short label identifying this entry within the repeated group.
+     */
     label;
-    /** 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.
+     */
     value;
-    /** Nested elements for structured entries */
+    /**
+     * Nested elements for structured entries
+     *
+     * @remarks
+     * Optional ordered content for entries that require more than one value element.
+     */
     elements;
     /**
      * 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, options) {
@@ -1200,7 +1683,7 @@ export class RepeatingGroupEntryClass extends ViewKitNode {
  * 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 class RepeatingGroupElementClass extends BaseUiElement {
     /**
@@ -1209,14 +1692,26 @@ export class RepeatingGroupElementClass extends BaseUiElement {
      * @defaultValue "repeating-group"
      */
     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.
+     */
     entries;
-    /** 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.
+     */
     title;
     /**
      * 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, options) {
@@ -1229,7 +1724,7 @@ export class RepeatingGroupElementClass extends BaseUiElement {
  * 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 class CollapsibleGroupElementClass extends BaseUiElement {
     /**
@@ -1238,15 +1733,33 @@ export class CollapsibleGroupElementClass extends BaseUiElement {
      * @defaultValue "collapsible-group"
      */
     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.
+     */
     title;
-    /** Nested content elements revealed when expanded */
+    /**
+     * Nested content elements revealed when expanded
+     *
+     * @remarks
+     * Ordered child elements made visible by expanding the group.
+     */
     elements;
-    /** 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.
+     */
     summary;
     /**
      * 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
      */
     defaultExpanded;
@@ -1254,7 +1767,11 @@ export class CollapsibleGroupElementClass extends BaseUiElement {
      * 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, elements, options) {
@@ -1269,7 +1786,7 @@ export class CollapsibleGroupElementClass extends BaseUiElement {
  * 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 class DividerElementClass extends BaseUiElement {
     /**
@@ -1281,6 +1798,9 @@ export class DividerElementClass extends BaseUiElement {
     /**
      * Line styling
      *
+     * @remarks
+     * Visual stroke treatment for the separator. Defaults to a subtle hairline.
+     *
      * @defaultValue DividerStyle.hairline
      */
     style;
@@ -1298,12 +1818,15 @@ export class DividerElementClass extends BaseUiElement {
  * 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 class EnvelopClass extends ViewKitNode {
     /**
      * 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"
      */
     schemaVersion;
@@ -1321,14 +1844,22 @@ export class EnvelopClass extends ViewKitNode {
  * 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 class UiContainerClass extends ViewKitNode {
-    /** 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.
+     */
     elements;
     /**
      * 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"
      */
     schemaVersion;
@@ -1336,6 +1867,8 @@ export class UiContainerClass extends ViewKitNode {
      * 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, options) {
@@ -1348,21 +1881,43 @@ export class UiContainerClass extends ViewKitNode {
  * 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 class UiCardClass extends ViewKitNode {
-    /** 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.
+     */
     title;
-    /** 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.
+     */
     elements;
-    /** 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.
+     */
     description;
-    /** 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.
+     */
     actions;
     /**
      * 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"
      */
     schemaVersion;
@@ -1370,7 +1925,11 @@ export class UiCardClass extends ViewKitNode {
      * 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, elements, options) {
@@ -1386,7 +1945,7 @@ export class UiCardClass extends ViewKitNode {
  * 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 class UiContainerBuilder {
     _elements = [];
@@ -1414,39 +1973,44 @@ export class UiContainerBuilder {
         return 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, options) {
-        return this.add(stringShort(value, options));
+    addString(value, options) {
+        return this.add(string(value, options));
     }
     /**
-     * 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, options) {
-        return this.add(stringLong(value, options));
+    addStrings(values, options) {
+        return this.add(strings(values, options));
     }
     /**
      * 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.
      */
@@ -1457,9 +2021,11 @@ export 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.
      */
@@ -1470,9 +2036,11 @@ export 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.
      */
@@ -1483,9 +2051,11 @@ export 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.
      */
@@ -1496,9 +2066,11 @@ export 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.
      */
@@ -1509,22 +2081,44 @@ export 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, options) {
         return this.add(ratio(value, options));
     }
+    /**
+     * 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, height, options) {
+        return this.add(dimensions(width, height, options));
+    }
     /**
      * 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.
      */
@@ -1535,9 +2129,11 @@ export 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.
      */
@@ -1548,9 +2144,11 @@ export 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.
      */
@@ -1561,9 +2159,11 @@ export 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.
      */
@@ -1574,9 +2174,11 @@ export 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.
      */
@@ -1587,9 +2189,11 @@ export 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.
      */
@@ -1600,9 +2204,11 @@ export 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.
      */
@@ -1610,38 +2216,29 @@ export class UiContainerBuilder {
         return this.add(numberMeter(value, options));
     }
     /**
-     * Appends a `BooleanPlainElement` component.
+     * Appends a `BooleanElement` component.
      *
      * @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.
      *
      * @param value - Boolean state value
-     * @param options - Optional component settings (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.
      */
-    addBooleanPlain(value, options) {
-        return this.add(booleanPlain(value, options));
-    }
-    /**
-     * Appends a `BooleanBadgeElement` component.
-     *
-     * @remarks
-     * Visual badge pill representation of a boolean state.
-     *
-     * @param value - Boolean state value
-     * @param options - Optional component settings (trueLabel (defaults to `true`), falseLabel (defaults to `false`), variant (defaults to `neutral`), modifiers).
-     * @returns This builder instance for method chaining.
-     */
-    addBooleanBadge(value, options) {
-        return this.add(booleanBadge(value, options));
+    addBoolean(value, options) {
+        return this.add(boolean(value, options));
     }
     /**
      * 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.
      */
@@ -1652,9 +2249,11 @@ export 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.
      */
@@ -1665,9 +2264,11 @@ export 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.
      */
@@ -1678,9 +2279,11 @@ export 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.
      */
@@ -1691,9 +2294,11 @@ export 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.
      */
@@ -1704,9 +2309,11 @@ export 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.
      */
@@ -1717,9 +2324,11 @@ export 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.
      */
@@ -1730,38 +2339,43 @@ export 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, options) {
-        return this.add(multiSlot(slots, options));
+    addMultiSlot(slots) {
+        return this.add(multiSlot(slots));
     }
     /**
      * 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) {
-        return this.add(flowing(elements));
+    addFlowing(elements, options) {
+        return this.add(flowing(elements, options));
     }
     /**
      * 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.
      */
@@ -1772,11 +2386,12 @@ export 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, options) {
@@ -1786,9 +2401,11 @@ export 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.
      */
@@ -1799,10 +2416,14 @@ export 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.
      */
@@ -1813,7 +2434,7 @@ export 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.
@@ -1887,7 +2508,7 @@ export 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.
@@ -1899,7 +2520,7 @@ export 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.
@@ -1912,8 +2533,7 @@ export function parseUiContainer(json, withDeepValidation = true) {
  * 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 class UiCardBuilder {
     _title;
@@ -1924,6 +2544,8 @@ export 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) {
         this._title = title;
@@ -1932,6 +2554,8 @@ export class UiCardBuilder {
      * 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) {
@@ -1979,39 +2603,44 @@ export class UiCardBuilder {
         return 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, options) {
-        return this.add(stringShort(value, options));
+    addString(value, options) {
+        return this.add(string(value, options));
     }
     /**
-     * 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, options) {
-        return this.add(stringLong(value, options));
+    addStrings(values, options) {
+        return this.add(strings(values, options));
     }
     /**
      * 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.
      */
@@ -2022,9 +2651,11 @@ export 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.
      */
@@ -2035,9 +2666,11 @@ export 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.
      */
@@ -2048,9 +2681,11 @@ export 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.
      */
@@ -2061,9 +2696,11 @@ export 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.
      */
@@ -2074,22 +2711,44 @@ export 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, options) {
         return this.add(ratio(value, options));
     }
+    /**
+     * 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, height, options) {
+        return this.add(dimensions(width, height, options));
+    }
     /**
      * 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.
      */
@@ -2100,9 +2759,11 @@ export 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.
      */
@@ -2113,9 +2774,11 @@ export 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.
      */
@@ -2126,9 +2789,11 @@ export 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.
      */
@@ -2139,9 +2804,11 @@ export 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.
      */
@@ -2152,9 +2819,11 @@ export 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.
      */
@@ -2165,9 +2834,11 @@ export 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.
      */
@@ -2175,38 +2846,29 @@ export class UiCardBuilder {
         return this.add(numberMeter(value, options));
     }
     /**
-     * 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, options) {
-        return this.add(booleanPlain(value, options));
-    }
-    /**
-     * 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, options) {
-        return this.add(booleanBadge(value, options));
+    addBoolean(value, options) {
+        return this.add(boolean(value, options));
     }
     /**
      * 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.
      */
@@ -2217,9 +2879,11 @@ export 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.
      */
@@ -2230,9 +2894,11 @@ export 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.
      */
@@ -2243,9 +2909,11 @@ export 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.
      */
@@ -2256,9 +2924,11 @@ export 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.
      */
@@ -2269,9 +2939,11 @@ export 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.
      */
@@ -2282,9 +2954,11 @@ export 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.
      */
@@ -2295,38 +2969,43 @@ export 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, options) {
-        return this.add(multiSlot(slots, options));
+    addMultiSlot(slots) {
+        return this.add(multiSlot(slots));
     }
     /**
      * 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) {
-        return this.add(flowing(elements));
+    addFlowing(elements, options) {
+        return this.add(flowing(elements, options));
     }
     /**
      * 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.
      */
@@ -2337,11 +3016,12 @@ export 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, options) {
@@ -2351,9 +3031,11 @@ export 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.
      */
@@ -2364,10 +3046,14 @@ export 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.
      */
@@ -2378,7 +3064,7 @@ export 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.
@@ -2420,6 +3106,8 @@ export 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) {
@@ -2459,10 +3147,11 @@ export 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.
  */
@@ -2476,8 +3165,7 @@ export function createUiCard(title, 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.
@@ -2491,9 +3179,11 @@ export function parseUiCard(json, withDeepValidation = true) {
  * 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.
  */
@@ -2507,7 +3197,7 @@ export function truncateOptions(characterLimit, 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.
@@ -2521,7 +3211,7 @@ export 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.
@@ -2536,38 +3226,43 @@ export function primitiveModifiers(options) {
     };
 }
 /**
- * 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 function stringShort(value, options) {
+export function string(value, options) {
     return {
-        type: "string-short",
+        type: "string",
         value,
-        representation: options?.representation ?? StringShortRepresentation.plain,
+        representation: options?.representation ?? StringRepresentation.plain,
         modifiers: options?.modifiers
     };
 }
 /**
- * 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 function stringLong(value, options) {
+export function strings(values, options) {
     return {
-        type: "string-long",
-        value,
+        type: "strings",
+        values: [...values],
+        representation: options?.representation ?? StringRepresentation.plain,
+        separator: options?.separator,
         modifiers: options?.modifiers
     };
 }
@@ -2575,9 +3270,11 @@ export function stringLong(value, options) {
  * 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.
  */
@@ -2593,9 +3290,11 @@ export function stringCode(value, 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.
  */
@@ -2610,9 +3309,11 @@ export function xml(value, 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.
  */
@@ -2627,9 +3328,11 @@ export function json(value, 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.
  */
@@ -2645,9 +3348,11 @@ export function stringUrl(value, 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.
  */
@@ -2662,9 +3367,11 @@ export function identifier(value, 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.
  */
@@ -2675,13 +3382,38 @@ export function ratio(value, options) {
         modifiers: options?.modifiers
     };
 }
+/**
+ * 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 function dimensions(width, height, options) {
+    return {
+        type: "dimensions",
+        width,
+        height,
+        modifiers: options?.modifiers
+    };
+}
 /**
  * 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.
  */
@@ -2700,9 +3432,11 @@ export function colour(value, 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.
  */
@@ -2721,9 +3455,11 @@ export function color(value, 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.
  */
@@ -2739,9 +3475,11 @@ export function numberUnbounded(value, 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.
  */
@@ -2757,9 +3495,11 @@ export function numberBoundedStars(value, 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.
  */
@@ -2775,9 +3515,11 @@ export function numberStars(value, 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.
  */
@@ -2796,9 +3538,11 @@ export function numberBoundedMeter(value, 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.
  */
@@ -2814,36 +3558,22 @@ export function numberMeter(value, options) {
     };
 }
 /**
- * Creates a `BooleanPlainElement` component instance.
+ * Creates a `BooleanElement` component instance.
  *
  * @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.
  *
  * @param value - Boolean state value
- * @param options - Optional settings (modifiers).
- * @returns A strongly-typed `BooleanPlainElement` 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 function booleanPlain(value, options) {
+export function boolean(value, options) {
     return {
-        type: "boolean-plain",
-        value,
-        modifiers: options?.modifiers
-    };
-}
-/**
- * Creates a `BooleanBadgeElement` component instance.
- *
- * @remarks
- * Visual badge pill representation of a boolean state.
- *
- * @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.
- */
-export function booleanBadge(value, options) {
-    return {
-        type: "boolean-badge",
+        type: "boolean",
         value,
+        representation: options?.representation ?? BooleanRepresentation.plain,
         trueLabel: options?.trueLabel ?? "true",
         falseLabel: options?.falseLabel ?? "false",
         variant: options?.variant ?? BadgeVariant.neutral,
@@ -2854,9 +3584,11 @@ export function booleanBadge(value, options) {
  * 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.
  */
@@ -2872,9 +3604,11 @@ export function timestamp(value, 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.
  */
@@ -2891,9 +3625,11 @@ export function imageReference(src, 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.
  */
@@ -2910,10 +3646,14 @@ export function imageRef(src, 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.
  */
@@ -2933,10 +3673,14 @@ export function buttonAction(commandId, label, 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 function externalLinkAction(url, label) {
@@ -2950,9 +3694,11 @@ export function externalLinkAction(url, label) {
  * 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.
  */
@@ -2967,9 +3713,11 @@ export function markdownBlock(content, 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.
  */
@@ -2984,9 +3732,11 @@ export function markdown(content, 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.
  */
@@ -3001,9 +3751,11 @@ export function htmlBlock(content, 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.
  */
@@ -3018,9 +3770,11 @@ export function html(content, 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.
  */
@@ -3035,45 +3789,50 @@ export function slot(content, options) {
  * 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 function multiSlot(slots, options) {
+export function multiSlot(slots) {
     return {
         type: "multi-slot",
-        slots: [...slots],
-        proportions: options?.proportions
+        slots: [...slots]
     };
 }
 /**
  * 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 function flowing(elements) {
+export function flowing(elements, options) {
     return {
         type: "flowing",
-        elements: [...elements]
+        elements: [...elements],
+        separator: options?.separator
     };
 }
 /**
  * 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.
  */
@@ -3089,25 +3848,28 @@ export function labelValue(label, value, 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 function tableColumn(options) {
     return {
         header: options?.header,
         align: options?.align ?? TableColumnAlign.left,
-        width: options?.width
+        width: options?.width,
+        widthMode: options?.widthMode ?? TableColumnWidthMode.fixed
     };
 }
 /**
  * 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 function tableRow(cells) {
@@ -3119,18 +3881,18 @@ export function tableRow(cells) {
  * 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 function table(rows, options) {
     return {
         type: "table",
         rows: [...rows],
-        hasHeader: options?.hasHeader ?? true,
         isStriped: options?.isStriped ?? false,
         withColumnSeparators: options?.withColumnSeparators ?? false,
         withRowSeparators: options?.withRowSeparators ?? false,
@@ -3141,9 +3903,11 @@ export function table(rows, 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.
  */
@@ -3158,9 +3922,11 @@ export function repeatingGroupEntry(label, 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.
  */
@@ -3175,10 +3941,14 @@ export function repeatingGroup(entries, 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.
  */
@@ -3195,7 +3965,7 @@ export function collapsibleGroup(title, elements, options) {
  * 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.
@@ -3210,7 +3980,7 @@ export 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.
@@ -3293,7 +4063,7 @@ export function isSlot(value, withDeepValidation = false) {
     }
     const element = value;
     return (element.label === undefined || typeof element.label === "string") &&
-        (element.width === undefined || typeof element.width === "string") &&
+        (element.width === undefined || typeof element.width === "number") &&
         ("content" in value && isUiElement(element.content, true));
 }
 /**
@@ -3313,7 +4083,8 @@ export function isTableColumn(value, withDeepValidation = false) {
     const element = value;
     return (element.header === undefined || typeof element.header === "string") &&
         (element.align === undefined || Object.values(TableColumnAlign).includes(element.align)) &&
-        (element.width === undefined || typeof element.width === "string");
+        (element.width === undefined || typeof element.width === "number") &&
+        (element.widthMode === undefined || Object.values(TableColumnWidthMode).includes(element.widthMode));
 }
 /**
  * Type guard predicate verifying whether an unknown value conforms to `TableRow`.
@@ -3384,10 +4155,10 @@ export function isUiElement(value, withDeepValidation = false) {
     }
     const element = value;
     switch (element.type) {
-        case "string-short":
-            return isStringShortElement(element, true);
-        case "string-long":
-            return isStringLongElement(element, true);
+        case "string":
+            return isStringElement(element, true);
+        case "strings":
+            return isStringsElement(element, true);
         case "string-code":
             return isStringCodeElement(element, true);
         case "xml":
@@ -3400,6 +4171,8 @@ export function isUiElement(value, withDeepValidation = false) {
             return isIdentifierElement(element, true);
         case "ratio":
             return isRatioElement(element, true);
+        case "dimensions":
+            return isDimensionsElement(element, true);
         case "color":
             return isColourElement(element, true);
         case "number-unbounded":
@@ -3408,10 +4181,8 @@ export function isUiElement(value, withDeepValidation = false) {
             return isNumberBoundedStarsElement(element, true);
         case "number-meter":
             return isNumberBoundedMeterElement(element, true);
-        case "boolean-plain":
-            return isBooleanPlainElement(element, true);
-        case "boolean-badge":
-            return isBooleanBadgeElement(element, true);
+        case "boolean":
+            return isBooleanElement(element, true);
         case "timestamp":
             return isTimestampElement(element, true);
         case "image-ref":
@@ -3439,14 +4210,14 @@ export function isUiElement(value, withDeepValidation = false) {
     }
 }
 /**
- * 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 function isStringShortElement(value, withDeepValidation = false) {
-    if (typeof value !== "object" || value === null || !("type" in value) || value.type !== "string-short") {
+export function isStringElement(value, withDeepValidation = false) {
+    if (typeof value !== "object" || value === null || !("type" in value) || value.type !== "string") {
         return false;
     }
     if (!withDeepValidation) {
@@ -3454,25 +4225,27 @@ export function isStringShortElement(value, withDeepValidation = false) {
     }
     const element = value;
     return ("value" in value && typeof element.value === "string") &&
-        (element.representation === undefined || Object.values(StringShortRepresentation).includes(element.representation)) &&
+        (element.representation === undefined || Object.values(StringRepresentation).includes(element.representation)) &&
         (element.modifiers === undefined || isPrimitiveModifiers(element.modifiers, true));
 }
 /**
- * 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 function isStringLongElement(value, withDeepValidation = false) {
-    if (typeof value !== "object" || value === null || !("type" in value) || value.type !== "string-long") {
+export function isStringsElement(value, withDeepValidation = false) {
+    if (typeof value !== "object" || value === null || !("type" in value) || value.type !== "strings") {
         return false;
     }
     if (!withDeepValidation) {
         return true;
     }
     const element = value;
-    return ("value" in value && typeof element.value === "string") &&
+    return ("values" in value && (Array.isArray(element.values) && element.values.every((item) => typeof item === "string"))) &&
+        (element.representation === undefined || Object.values(StringRepresentation).includes(element.representation)) &&
+        (element.separator === undefined || Object.values(Separator).includes(element.separator)) &&
         (element.modifiers === undefined || isPrimitiveModifiers(element.modifiers, true));
 }
 /**
@@ -3585,6 +4358,25 @@ export function isRatioElement(value, withDeepValidation = false) {
     return ("value" in value && typeof element.value === "number") &&
         (element.modifiers === undefined || isPrimitiveModifiers(element.modifiers, true));
 }
+/**
+ * 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 function isDimensionsElement(value, withDeepValidation = false) {
+    if (typeof value !== "object" || value === null || !("type" in value) || value.type !== "dimensions") {
+        return false;
+    }
+    if (!withDeepValidation) {
+        return true;
+    }
+    const element = value;
+    return ("width" in value && typeof element.width === "number") &&
+        ("height" in value && typeof element.height === "number") &&
+        (element.modifiers === undefined || isBaseModifiers(element.modifiers, true));
+}
 /**
  * Type guard predicate narrowing a value to `ColourElement`.
  *
@@ -3668,32 +4460,14 @@ export function isNumberBoundedMeterElement(value, withDeepValidation = false) {
         (element.modifiers === undefined || isPrimitiveModifiers(element.modifiers, true));
 }
 /**
- * Type guard predicate narrowing a value to `BooleanPlainElement`.
+ * 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 `BooleanPlainElement` (type = "boolean-plain"), otherwise `false`.
+ * @returns `true` if the value is a `BooleanElement` (type = "boolean"), otherwise `false`.
  */
-export function isBooleanPlainElement(value, withDeepValidation = false) {
-    if (typeof value !== "object" || value === null || !("type" in value) || value.type !== "boolean-plain") {
-        return false;
-    }
-    if (!withDeepValidation) {
-        return true;
-    }
-    const element = value;
-    return ("value" in value && typeof element.value === "boolean") &&
-        (element.modifiers === undefined || isPrimitiveModifiers(element.modifiers, true));
-}
-/**
- * Type guard predicate narrowing a value to `BooleanBadgeElement`.
- *
- * @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`.
- */
-export function isBooleanBadgeElement(value, withDeepValidation = false) {
-    if (typeof value !== "object" || value === null || !("type" in value) || value.type !== "boolean-badge") {
+export function isBooleanElement(value, withDeepValidation = false) {
+    if (typeof value !== "object" || value === null || !("type" in value) || value.type !== "boolean") {
         return false;
     }
     if (!withDeepValidation) {
@@ -3701,6 +4475,7 @@ export function isBooleanBadgeElement(value, withDeepValidation = false) {
     }
     const element = value;
     return ("value" in value && typeof element.value === "boolean") &&
+        (element.representation === undefined || Object.values(BooleanRepresentation).includes(element.representation)) &&
         (element.trueLabel === undefined || typeof element.trueLabel === "string") &&
         (element.falseLabel === undefined || typeof element.falseLabel === "string") &&
         (element.variant === undefined || Object.values(BadgeVariant).includes(element.variant)) &&
@@ -3796,8 +4571,7 @@ export function isMultiSlotElement(value, withDeepValidation = false) {
         return true;
     }
     const element = value;
-    return (element.proportions === undefined || typeof element.proportions === "string") &&
-        ("slots" in value && (Array.isArray(element.slots) && element.slots.every((item) => isSlot(item, true))));
+    return ("slots" in value && (Array.isArray(element.slots) && element.slots.every((item) => isSlot(item, true))));
 }
 /**
  * Type guard predicate narrowing a value to `FlowingElement`.
@@ -3814,7 +4588,8 @@ export function isFlowingElement(value, withDeepValidation = false) {
         return true;
     }
     const element = value;
-    return ("elements" in value && (Array.isArray(element.elements) && element.elements.every((item) => isUiElement(item, true))));
+    return (element.separator === undefined || Object.values(Separator).includes(element.separator)) &&
+        ("elements" in value && (Array.isArray(element.elements) && element.elements.every((item) => isUiElement(item, true))));
 }
 /**
  * Type guard predicate narrowing a value to `LabelValueElement`.
@@ -3850,8 +4625,7 @@ export function isTableElement(value, withDeepValidation = false) {
         return true;
     }
     const element = value;
-    return (element.hasHeader === undefined || typeof element.hasHeader === "boolean") &&
-        (element.isStriped === undefined || typeof element.isStriped === "boolean") &&
+    return (element.isStriped === undefined || typeof element.isStriped === "boolean") &&
         (element.withColumnSeparators === undefined || typeof element.withColumnSeparators === "boolean") &&
         (element.withRowSeparators === undefined || typeof element.withRowSeparators === "boolean") &&
         (element.columns === undefined || (Array.isArray(element.columns) && element.columns.every((item) => isTableColumn(item, true)))) &&