@picteus/extension-sdk 0.18.0 → 0.20.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,147 +41,170 @@ 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 = {}));
+/** Measurement unit for text truncation. */
+export var TruncateMode;
+(function (TruncateMode) {
+    /** Truncate by total character count */
+    TruncateMode["characters"] = "characters";
+    /** Truncate by number of rendered lines */
+    TruncateMode["lines"] = "lines";
+})(TruncateMode || (TruncateMode = {}));
 /** Visual presentation style for string values. */
 export var StringRepresentation;
 (function (StringRepresentation) {
-    // Standard inline text rendering
+    /** Standard inline text rendering */
     StringRepresentation["plain"] = "plain";
-    // Visual chip / tag pill representation
+    /** Visual chip / tag pill representation */
     StringRepresentation["chip"] = "chip";
-    // Multiline text with preserved whitespace and line breaks
+    /** 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
+    /** Vertical dividing bar */
     Separator["bar"] = "bar";
-    // Comma separator
+    /** Comma separator */
     Separator["comma"] = "comma";
-    // Bullet dot separator
+    /** Bullet dot separator */
     Separator["dot"] = "dot";
-    // Forward slash separator
+    /** Forward slash separator */
     Separator["slash"] = "slash";
-    // Dash separator
+    /** Dash separator */
     Separator["dash"] = "dash";
-    // Space separator
+    /** 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)
+    /** Standard inline text rendering (e.g. "true" / "false" or custom labels) */
     BooleanRepresentation["plain"] = "plain";
-    // Visual badge pill representation
+    /** 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 = {}));
-/** Width mode for table columns. */
+/**
+ * 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
+    /** Fixed width constraint */
     TableColumnWidthMode["fixed"] = "fixed";
-    // Maximum width upper bound constraint
+    /** Maximum width upper bound constraint */
     TableColumnWidthMode["maximum"] = "maximum";
 })(TableColumnWidthMode || (TableColumnWidthMode = {}));
-/** Visual styling variants for hairline dividers. */
+/**
+ * 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. */
@@ -195,26 +218,46 @@ 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. When mode is characters, limit represents maximum character count; when mode is lines, limit represents visual line count.
  */
 export class TruncateOptionsClass extends ViewKitNode {
-    /** Maximum number of characters to display before truncating */
-    characterLimit;
+    /**
+     * Maximum threshold limit before truncating
+     *
+     * @remarks
+     * Threshold after which the renderer can shorten the displayed text. When mode is characters, this represents character count; when mode is lines, this represents visual line count.
+     */
+    limit;
+    /**
+     * Truncation measurement mode (characters or lines)
+     *
+     * @remarks
+     * Whether limit represents character count or line count. Defaults to lines.
+     *
+     * @defaultValue TruncateMode.lines
+     */
+    mode;
     /**
      * 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;
     /**
      * Constructs a new `TruncateOptionsClass` instance.
      *
-     * @param characterLimit - Maximum number of characters to display before truncating
-     * @param options - Optional component settings. (showMore (defaults to `true`)).
+     * @param limit - Maximum threshold limit before truncating
+  
+    Threshold after which the renderer can shorten the displayed text. When mode is characters, this represents character count; when mode is lines, this represents visual line count.
+     * @param options - Optional component settings. (mode (defaults to `lines`), showMore (defaults to `true`)).
      */
-    constructor(characterLimit, options) {
+    constructor(limit, options) {
         super();
-        this.characterLimit = characterLimit;
+        this.limit = limit;
+        this.mode = options?.mode ?? TruncateMode.lines;
         this.showMore = options?.showMore ?? true;
     }
 }
@@ -222,10 +265,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.
@@ -241,30 +289,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 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.
@@ -284,8 +351,7 @@ export class PrimitiveModifiersClass extends ViewKitNode {
  * Class implementation of the `StringElement` interface.
  *
  * @remarks
- * Universal textual string primitive element.
- * Supports plain text, compact chip pill, or multiline pre-wrapped 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 StringElementClass extends BaseUiElement {
     /**
@@ -294,11 +360,19 @@ export class StringElementClass extends BaseUiElement {
      * @defaultValue "string"
      */
     type = "string";
-    /** Text value */
+    /**
+     * Text value
+     *
+     * @remarks
+     * Text to render. Supply plain text; this field is not a Markdown or HTML document.
+     */
     value;
     /**
      * Display representation mode
      *
+     * @remarks
+     * Selects inline, chip, or multiline rendering. The default is plain, so callers can omit this for ordinary text.
+     *
      * @defaultValue StringRepresentation.plain
      */
     representation;
@@ -308,6 +382,8 @@ export class StringElementClass extends BaseUiElement {
      * 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) {
@@ -321,8 +397,7 @@ export class StringElementClass extends BaseUiElement {
  * Class implementation of the `StringsElement` interface.
  *
  * @remarks
- * Collection of textual string values rendered as a sequence of inline items or chips.
- * Supports visual separators (comma, dot, slash, bar, dash, space) and copyable affordance.
+ * 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 StringsElementClass extends BaseUiElement {
     /**
@@ -331,15 +406,28 @@ export class StringsElementClass extends BaseUiElement {
      * @defaultValue "strings"
      */
     type = "strings";
-    /** Array of string values */
+    /**
+     * 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 */
+    /**
+     * 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;
@@ -347,6 +435,8 @@ export class StringsElementClass extends BaseUiElement {
      * Constructs a new `StringsElementClass` instance.
      *
      * @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(values, options) {
@@ -361,7 +451,7 @@ export class StringsElementClass 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 {
     /**
@@ -370,9 +460,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;
@@ -380,6 +480,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) {
@@ -393,7 +495,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 {
     /**
@@ -402,7 +504,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;
@@ -410,6 +517,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) {
@@ -422,7 +531,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 {
     /**
@@ -431,7 +540,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;
@@ -439,6 +553,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) {
@@ -451,7 +567,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 {
     /**
@@ -460,7 +576,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;
@@ -470,6 +591,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) {
@@ -483,7 +606,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 {
     /**
@@ -492,7 +615,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;
@@ -500,6 +628,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) {
@@ -512,7 +642,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 {
     /**
@@ -521,7 +651,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;
@@ -529,6 +664,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) {
@@ -541,7 +678,7 @@ export class RatioElementClass extends BaseUiElement {
  * Class implementation of the `DimensionsElement` interface.
  *
  * @remarks
- * Image dimensions representation displaying formatted width and height in pixels.
+ * 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 {
     /**
@@ -550,9 +687,19 @@ export class DimensionsElementClass extends BaseUiElement {
      * @defaultValue "dimensions"
      */
     type = "dimensions";
-    /** Width in pixels */
+    /**
+     * Width in pixels
+     *
+     * @remarks
+     * Horizontal pixel count. Values below one are rejected by the schema constraint.
+     */
     width;
-    /** Height in pixels */
+    /**
+     * Height in pixels
+     *
+     * @remarks
+     * Vertical pixel count. Values below one are rejected by the schema constraint.
+     */
     height;
     /** Optional visual modifiers (copyable) */
     modifiers;
@@ -560,7 +707,11 @@ export class DimensionsElementClass extends BaseUiElement {
      * 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) {
@@ -574,7 +725,7 @@ export class DimensionsElementClass extends BaseUiElement {
  * 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 {
     /**
@@ -583,25 +734,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;
@@ -611,6 +781,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) {
@@ -627,7 +799,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 {
     /**
@@ -636,9 +808,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;
@@ -646,6 +828,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) {
@@ -659,7 +843,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 {
     /**
@@ -668,9 +852,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;
@@ -678,6 +872,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) {
@@ -691,7 +887,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 {
     /**
@@ -700,15 +896,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;
@@ -716,6 +937,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) {
@@ -732,8 +955,7 @@ export class NumberBoundedMeterElementClass extends BaseUiElement {
  * Class implementation of the `BooleanElement` interface.
  *
  * @remarks
- * Universal boolean primitive element.
- * Supports standard plain text or badge pill presentation with customizable labels and variants.
+ * 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 BooleanElementClass extends BaseUiElement {
     /**
@@ -742,29 +964,46 @@ export class BooleanElementClass extends BaseUiElement {
      * @defaultValue "boolean"
      */
     type = "boolean";
-    /** Boolean state value */
+    /**
+     * Boolean state value
+     *
+     * @remarks
+     * State to display. This remains a boolean value in the data model even when the renderer substitutes custom labels.
+     */
     value;
     /**
      * Display representation mode
      *
+     * @remarks
+     * Selects ordinary text or a badge pill. Badge color applies only to badge presentation.
+     *
      * @defaultValue BooleanRepresentation.plain
      */
     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 when rendered as badge
      *
+     * @remarks
+     * Semantic color treatment for badge presentation; it has no effect in plain representation.
+     *
      * @defaultValue BadgeVariant.neutral
      */
     variant;
@@ -774,6 +1013,8 @@ export class BooleanElementClass extends BaseUiElement {
      * Constructs a new `BooleanElementClass` instance.
      *
      * @param value - Boolean state value
+  
+    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) {
@@ -790,7 +1031,7 @@ export class BooleanElementClass 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 {
     /**
@@ -799,11 +1040,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;
@@ -813,6 +1062,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) {
@@ -826,7 +1077,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 {
     /**
@@ -835,22 +1086,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) {
@@ -865,7 +1136,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 {
     /**
@@ -874,25 +1145,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;
@@ -900,7 +1202,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) {
@@ -918,7 +1224,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 {
     /**
@@ -927,15 +1233,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();
@@ -947,7 +1267,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 {
     /**
@@ -956,7 +1276,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;
@@ -964,6 +1289,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) {
@@ -976,7 +1303,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 {
     /**
@@ -985,7 +1312,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;
@@ -993,6 +1325,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) {
@@ -1005,19 +1339,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;
-    /** Width percentage (1-100) */
+    /**
+     * 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) {
@@ -1031,7 +1382,7 @@ export class SlotClass extends ViewKitNode {
  * Class implementation of the `MultiSlotElement` interface.
  *
  * @remarks
- * Multi-slot horizontal row layout comprising slots with individual widths.
+ * 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 {
     /**
@@ -1040,12 +1391,19 @@ 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;
     /**
      * Constructs a new `MultiSlotElementClass` instance.
      *
      * @param slots - List of slots comprising the row
+  
+    Ordered slots in the row. Each slot's width is a percentage; arrange slot definitions in the intended visual order.
      */
     constructor(slots) {
         super();
@@ -1056,8 +1414,7 @@ export class MultiSlotElementClass extends BaseUiElement {
  * 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 {
     /**
@@ -1066,14 +1423,26 @@ 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 */
+    /**
+     * 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, options) {
@@ -1086,8 +1455,7 @@ export class FlowingElementClass extends BaseUiElement {
  * 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 {
     /**
@@ -1096,13 +1464,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;
@@ -1110,7 +1491,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) {
@@ -1124,22 +1509,38 @@ 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;
-    /** Width percentage (1-100) */
+    /**
+     * 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;
@@ -1160,15 +1561,22 @@ export class TableColumnClass extends ViewKitNode {
  * 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();
@@ -1179,8 +1587,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 {
     /**
@@ -1189,32 +1596,53 @@ export class TableElementClass extends BaseUiElement {
      * @defaultValue "table"
      */
     type = "table";
-    /** Tabular data rows */
+    /**
+     * Tabular data rows
+     *
+     * @remarks
+     * Ordered table rows. Each row's cells correspond positionally to the declared columns.
+     */
     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
+  
+    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) {
@@ -1230,19 +1658,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) {
@@ -1256,7 +1701,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 {
     /**
@@ -1265,14 +1710,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) {
@@ -1285,7 +1742,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 {
     /**
@@ -1294,15 +1751,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;
@@ -1310,7 +1785,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) {
@@ -1325,7 +1804,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 {
     /**
@@ -1337,6 +1816,9 @@ export class DividerElementClass extends BaseUiElement {
     /**
      * Line styling
      *
+     * @remarks
+     * Visual stroke treatment for the separator. Defaults to a subtle hairline.
+     *
      * @defaultValue DividerStyle.hairline
      */
     style;
@@ -1354,12 +1836,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;
@@ -1377,14 +1862,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;
@@ -1392,6 +1885,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) {
@@ -1404,21 +1899,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;
@@ -1426,7 +1943,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) {
@@ -1442,7 +1963,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 = [];
@@ -1473,10 +1994,11 @@ export class UiContainerBuilder {
      * Appends a `StringElement` component.
      *
      * @remarks
-     * Universal textual string primitive element.
-     * Supports plain text, compact chip pill, or multiline pre-wrapped 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.
      */
@@ -1487,10 +2009,11 @@ export class UiContainerBuilder {
      * Appends a `StringsElement` component.
      *
      * @remarks
-     * Collection of textual string values rendered as a sequence of inline items or chips.
-     * Supports visual separators (comma, dot, slash, bar, dash, space) and copyable affordance.
+     * 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 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.
      */
@@ -1501,9 +2024,11 @@ export class UiContainerBuilder {
      * 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.
      */
@@ -1514,9 +2039,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.
      */
@@ -1527,9 +2054,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.
      */
@@ -1540,9 +2069,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.
      */
@@ -1553,9 +2084,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.
      */
@@ -1566,9 +2099,11 @@ 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.
      */
@@ -1579,10 +2114,14 @@ export class UiContainerBuilder {
      * Appends a `DimensionsElement` component.
      *
      * @remarks
-     * Image dimensions representation displaying formatted width and height in pixels.
+     * 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.
      */
@@ -1593,9 +2132,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.
      */
@@ -1606,9 +2147,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.
      */
@@ -1619,9 +2162,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.
      */
@@ -1632,9 +2177,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.
      */
@@ -1645,9 +2192,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.
      */
@@ -1658,9 +2207,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.
      */
@@ -1671,9 +2222,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.
      */
@@ -1684,10 +2237,11 @@ export class UiContainerBuilder {
      * Appends a `BooleanElement` component.
      *
      * @remarks
-     * Universal boolean primitive element.
-     * Supports standard plain text or badge pill presentation with customizable labels and variants.
+     * 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
+  
+    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.
      */
@@ -1698,9 +2252,11 @@ export class UiContainerBuilder {
      * Appends a `TimestampElement` component.
      *
      * @remarks
-     * Formatted date and time representation.
+     * Displays an epoch timestamp using a selected date/time format. The input is a count of milliseconds, not seconds; relative formatting is interpreted by the consumer.
      *
      * @param value - The timestamp in milliseconds
+  
+    Unix epoch timestamp measured in milliseconds. Convert seconds-based timestamps before assigning this value.
      * @param options - Optional component settings (format (defaults to `datetime`), modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -1711,9 +2267,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.
      */
@@ -1724,9 +2282,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.
      */
@@ -1737,9 +2297,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.
      */
@@ -1750,9 +2312,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.
      */
@@ -1763,9 +2327,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.
      */
@@ -1776,9 +2342,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.
      */
@@ -1789,9 +2357,11 @@ export class UiContainerBuilder {
      * Appends a `MultiSlotElement` component.
      *
      * @remarks
-     * Multi-slot horizontal row layout comprising slots with individual widths.
+     * 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
+  
+    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) {
@@ -1801,10 +2371,11 @@ export class UiContainerBuilder {
      * 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.
      */
@@ -1815,11 +2386,14 @@ export class UiContainerBuilder {
      * 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.
      */
@@ -1830,10 +2404,11 @@ 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
+  
+    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.
      */
@@ -1844,9 +2419,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.
      */
@@ -1857,10 +2434,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.
      */
@@ -1871,7 +2452,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.
@@ -1945,7 +2526,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.
@@ -1957,7 +2538,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.
@@ -1970,8 +2551,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;
@@ -1982,6 +2562,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;
@@ -1990,6 +2572,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) {
@@ -2040,10 +2624,11 @@ export class UiCardBuilder {
      * Appends a `StringElement` component.
      *
      * @remarks
-     * Universal textual string primitive element.
-     * Supports plain text, compact chip pill, or multiline pre-wrapped 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.
      */
@@ -2054,10 +2639,11 @@ export class UiCardBuilder {
      * Appends a `StringsElement` component.
      *
      * @remarks
-     * Collection of textual string values rendered as a sequence of inline items or chips.
-     * Supports visual separators (comma, dot, slash, bar, dash, space) and copyable affordance.
+     * 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 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.
      */
@@ -2068,9 +2654,11 @@ export class UiCardBuilder {
      * 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.
      */
@@ -2081,9 +2669,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.
      */
@@ -2094,9 +2684,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.
      */
@@ -2107,9 +2699,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.
      */
@@ -2120,9 +2714,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.
      */
@@ -2133,9 +2729,11 @@ 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.
      */
@@ -2146,10 +2744,14 @@ export class UiCardBuilder {
      * Appends a `DimensionsElement` component.
      *
      * @remarks
-     * Image dimensions representation displaying formatted width and height in pixels.
+     * 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.
      */
@@ -2160,9 +2762,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.
      */
@@ -2173,9 +2777,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.
      */
@@ -2186,9 +2792,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.
      */
@@ -2199,9 +2807,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.
      */
@@ -2212,9 +2822,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.
      */
@@ -2225,9 +2837,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.
      */
@@ -2238,9 +2852,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.
      */
@@ -2251,10 +2867,11 @@ export class UiCardBuilder {
      * Appends a `BooleanElement` component.
      *
      * @remarks
-     * Universal boolean primitive element.
-     * Supports standard plain text or badge pill presentation with customizable labels and variants.
+     * 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
+  
+    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.
      */
@@ -2265,9 +2882,11 @@ export class UiCardBuilder {
      * Appends a `TimestampElement` component.
      *
      * @remarks
-     * Formatted date and time representation.
+     * Displays an epoch timestamp using a selected date/time format. The input is a count of milliseconds, not seconds; relative formatting is interpreted by the consumer.
      *
      * @param value - The timestamp in milliseconds
+  
+    Unix epoch timestamp measured in milliseconds. Convert seconds-based timestamps before assigning this value.
      * @param options - Optional component settings (format (defaults to `datetime`), modifiers).
      * @returns This builder instance for method chaining.
      */
@@ -2278,9 +2897,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.
      */
@@ -2291,9 +2912,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.
      */
@@ -2304,9 +2927,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.
      */
@@ -2317,9 +2942,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.
      */
@@ -2330,9 +2957,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.
      */
@@ -2343,9 +2972,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.
      */
@@ -2356,9 +2987,11 @@ export class UiCardBuilder {
      * Appends a `MultiSlotElement` component.
      *
      * @remarks
-     * Multi-slot horizontal row layout comprising slots with individual widths.
+     * 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
+  
+    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) {
@@ -2368,10 +3001,11 @@ export class UiCardBuilder {
      * 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.
      */
@@ -2382,11 +3016,14 @@ export class UiCardBuilder {
      * 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.
      */
@@ -2397,10 +3034,11 @@ 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
+  
+    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.
      */
@@ -2411,9 +3049,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.
      */
@@ -2424,10 +3064,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.
      */
@@ -2438,7 +3082,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.
@@ -2480,6 +3124,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) {
@@ -2519,10 +3165,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.
  */
@@ -2536,8 +3183,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.
@@ -2551,15 +3197,18 @@ 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. When mode is characters, limit represents maximum character count; when mode is lines, limit represents visual line count.
  *
- * @param characterLimit - Maximum number of characters to display before truncating
- * @param options - Optional settings (showMore (defaults to `true`)).
+ * @param limit - Maximum threshold limit before truncating
+
+Threshold after which the renderer can shorten the displayed text. When mode is characters, this represents character count; when mode is lines, this represents visual line count.
+ * @param options - Optional settings (mode (defaults to `lines`), showMore (defaults to `true`)).
  * @returns A strongly-typed `TruncateOptions` object.
  */
-export function truncateOptions(characterLimit, options) {
+export function truncateOptions(limit, options) {
     return {
-        characterLimit,
+        limit,
+        mode: options?.mode ?? TruncateMode.lines,
         showMore: options?.showMore ?? true
     };
 }
@@ -2567,7 +3216,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.
@@ -2581,7 +3230,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.
@@ -2599,10 +3248,11 @@ export function primitiveModifiers(options) {
  * Creates a `StringElement` component instance.
  *
  * @remarks
- * Universal textual string primitive element.
- * Supports plain text, compact chip pill, or multiline pre-wrapped 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 `StringElement` object.
  */
@@ -2618,10 +3268,11 @@ export function string(value, options) {
  * Creates a `StringsElement` component instance.
  *
  * @remarks
- * Collection of textual string values rendered as a sequence of inline items or chips.
- * Supports visual separators (comma, dot, slash, bar, dash, space) and copyable affordance.
+ * 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 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.
  */
@@ -2638,9 +3289,11 @@ export function strings(values, 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.
  */
@@ -2656,9 +3309,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.
  */
@@ -2673,9 +3328,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.
  */
@@ -2690,9 +3347,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.
  */
@@ -2708,9 +3367,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.
  */
@@ -2725,9 +3386,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.
  */
@@ -2742,10 +3405,14 @@ export function ratio(value, options) {
  * Creates a `DimensionsElement` component instance.
  *
  * @remarks
- * Image dimensions representation displaying formatted width and height in pixels.
+ * 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.
  */
@@ -2761,9 +3428,11 @@ export function dimensions(width, height, 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.
  */
@@ -2782,9 +3451,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.
  */
@@ -2803,9 +3474,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.
  */
@@ -2821,9 +3494,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.
  */
@@ -2839,9 +3514,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.
  */
@@ -2857,9 +3534,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.
  */
@@ -2878,9 +3557,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.
  */
@@ -2899,10 +3580,11 @@ export function numberMeter(value, options) {
  * Creates a `BooleanElement` component instance.
  *
  * @remarks
- * Universal boolean primitive element.
- * Supports standard plain text or badge pill presentation with customizable labels and variants.
+ * 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
+
+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.
  */
@@ -2921,9 +3603,11 @@ export function boolean(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.
  */
@@ -2939,9 +3623,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.
  */
@@ -2958,9 +3644,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.
  */
@@ -2977,10 +3665,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.
  */
@@ -3000,10 +3692,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) {
@@ -3017,9 +3713,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.
  */
@@ -3034,9 +3732,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.
  */
@@ -3051,9 +3751,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.
  */
@@ -3068,9 +3770,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.
  */
@@ -3085,9 +3789,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.
  */
@@ -3102,9 +3808,11 @@ export function slot(content, options) {
  * Creates a `MultiSlotElement` component instance.
  *
  * @remarks
- * Multi-slot horizontal row layout comprising slots with individual widths.
+ * 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
+
+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) {
@@ -3117,10 +3825,11 @@ export function multiSlot(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.
  */
@@ -3135,11 +3844,14 @@ export function flowing(elements, options) {
  * 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.
  */
@@ -3155,7 +3867,7 @@ 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, widthMode (defaults to `fixed`)).
  * @returns A strongly-typed `TableColumn` object.
@@ -3172,9 +3884,11 @@ export function tableColumn(options) {
  * 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) {
@@ -3186,10 +3900,11 @@ 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
+
+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.
  */
@@ -3207,9 +3922,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.
  */
@@ -3224,9 +3941,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.
  */
@@ -3241,10 +3960,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.
  */
@@ -3261,7 +3984,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.
@@ -3276,7 +3999,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.
@@ -3302,7 +4025,8 @@ export function isTruncateOptions(value, withDeepValidation = false) {
         return true;
     }
     const element = value;
-    return ("characterLimit" in value && typeof element.characterLimit === "number") &&
+    return ("limit" in value && typeof element.limit === "number") &&
+        (element.mode === undefined || Object.values(TruncateMode).includes(element.mode)) &&
         (element.showMore === undefined || typeof element.showMore === "boolean");
 }
 /**