@almadar/core 2.5.0 → 2.5.2

package/dist/{schema-BrFR8WMF.d.ts → schema-obC5T1Jm.d.ts}

@@ -63,17 +63,52 @@ declare const ExpressionSchema: z.ZodType<Expression>;
 declare function isSExpr(value: unknown): value is SExpr[];
 /**
  * Type guard for S-expression atoms (non-array values).
- * Includes objects (for payload data, props, etc.)
+ *
+ * Validates that a value is an S-expression atom (literal value).
+ * Includes null, strings, numbers, booleans, and objects. Used to
+ * distinguish atomic values from S-expression calls (arrays).
+ *
+ * @param {unknown} value - Value to check
+ * @returns {boolean} True if value is an S-expression atom, false otherwise
+ *
+ * @example
+ * isSExprAtom('hello'); // returns true
+ * isSExprAtom(42); // returns true
+ * isSExprAtom(null); // returns true
+ * isSExprAtom({ key: 'value' }); // returns true
+ * isSExprAtom(['+', 1, 2]); // returns false
  */
 declare function isSExprAtom(value: unknown): value is SExprAtom;
 /**
- * Check if a value is a binding reference.
- * Bindings start with @ (e.g., @entity.health, @payload.amount, @now)
+ * Checks if a value is a binding reference.
+ *
+ * Validates that a string is a binding reference (starts with @).
+ * Bindings reference runtime values like @entity.health, @payload.amount, @now.
+ * Used for identifying bindings in S-expressions and validation.
+ *
+ * @param {unknown} value - Value to check
+ * @returns {boolean} True if value is a binding reference, false otherwise
+ *
+ * @example
+ * isBinding('@entity.health'); // returns true
+ * isBinding('@payload.amount'); // returns true
+ * isBinding('not-a-binding'); // returns false
+ * isBinding(123); // returns false
  */
 declare function isBinding(value: unknown): value is string;
 /**
- * Check if a value is a valid S-expression call (array with operator).
- * Use this to distinguish between S-expression calls and atom values.
+ * Checks if a value is a valid S-expression call (array with operator).
+ *
+ * Alias for isSExpr() - validates S-expression call structure.
+ * Used to distinguish between S-expression calls and atom values.
+ *
+ * @param {unknown} value - Value to check
+ * @returns {boolean} True if value is a valid S-expression call, false otherwise
+ *
+ * @example
+ * isSExprCall(['+', 1, 2]); // returns true
+ * isSExprCall(['set', '@entity.health', 100]); // returns true
+ * isSExprCall('not-a-call'); // returns false
  */
 declare function isSExprCall(value: unknown): value is SExpr[];
 /**
@@ -96,11 +131,19 @@ interface ParsedBinding {
 declare const CORE_BINDINGS: readonly ["entity", "payload", "state", "now", "config", "computed", "trait"];
 type CoreBinding = (typeof CORE_BINDINGS)[number];
 /**
- * Parse a binding reference into its components.
- * Does NOT use regex - uses structured string operations.
+ * Parses a binding reference into its components.
+ *
+ * Deconstructs a binding string (e.g., '@entity.health') into its constituent
+ * parts: type, root, path, and original string. Does NOT use regex - uses
+ * structured string operations for reliability and maintainability.
  *
- * @param binding - Binding string starting with @
- * @returns Parsed binding object or null if invalid
+ * @param {string} binding - Binding string starting with @
+ * @returns {ParsedBinding | null} Parsed binding object or null if invalid
+ *
+ * @example
+ * parseBinding('@entity.health'); // returns { type: 'core', root: 'entity', path: ['health'], original: '@entity.health' }
+ * parseBinding('@User.name'); // returns { type: 'entity', root: 'User', path: ['name'], original: '@User.name' }
+ * parseBinding('not-a-binding'); // returns null
  */
 declare function parseBinding(binding: string): ParsedBinding | null;
 /**
@@ -569,22 +612,65 @@ type AssetMappingInput = z.input<typeof AssetMappingSchema>;
 type AssetMapInput = z.input<typeof AssetMapSchema>;
 type AnimationDefInput = z.input<typeof AnimationDefSchema>;
 /**
- * Create a semantic asset key from role and category
+ * Creates a semantic asset key from role and category.
+ *
+ * Generates a unique asset identifier by combining role and category
+ * with a colon separator. Used for asset management and lookup.
+ *
+ * @param {EntityRole} role - Entity role (e.g., 'player', 'enemy')
+ * @param {string} category - Asset category (e.g., 'sprite', 'animation')
+ * @returns {string} Asset key in format 'role:category'
+ *
+ * @example
+ * createAssetKey('player', 'sprite'); // returns 'player:sprite'
+ * createAssetKey('enemy', 'animation'); // returns 'enemy:animation'
  */
 declare function createAssetKey(role: EntityRole, category: string): string;
 /**
- * Parse an asset key into role and category
+ * Parses an asset key into role and category components.
+ *
+ * Deconstructs an asset key string (format 'role:category') into its
+ * constituent parts. Returns null if the key format is invalid.
+ *
+ * @param {string} key - Asset key in format 'role:category'
+ * @returns {{ role: string; category: string } | null} Parsed components or null
+ *
+ * @example
+ * parseAssetKey('player:sprite'); // returns { role: 'player', category: 'sprite' }
+ * parseAssetKey('enemy:animation'); // returns { role: 'enemy', category: 'animation' }
+ * parseAssetKey('invalid'); // returns null
  */
 declare function parseAssetKey(key: string): {
     role: string;
     category: string;
 } | null;
 /**
- * Get common animations for an entity role
+ * Gets common animations for an entity role.
+ *
+ * Returns an array of default animation names appropriate for the
+ * specified entity role. Used for asset configuration and validation.
+ *
+ * @param {EntityRole} role - Entity role
+ * @returns {string[]} Array of default animation names
+ *
+ * @example
+ * getDefaultAnimationsForRole('player'); // returns ['idle', 'run', 'jump', 'fall', 'attack', 'hurt', 'die']
+ * getDefaultAnimationsForRole('enemy'); // returns ['idle', 'walk', 'attack', 'hurt', 'die']
  */
 declare function getDefaultAnimationsForRole(role: EntityRole): string[];
 /**
- * Validate that an asset ref has required animations
+ * Validates that an asset reference has required animations.
+ *
+ * Checks if an asset reference contains all required animations.
+ * Returns an error message if validation fails, or null if valid.
+ *
+ * @param {SemanticAssetRef} assetRef - Asset reference to validate
+ * @param {string[]} requiredAnimations - Required animation names
+ * @returns {string | null} Error message or null if valid
+ *
+ * @example
+ * validateAssetAnimations(assetRef, ['idle', 'run']); // returns null if valid
+ * validateAssetAnimations(assetRef, ['missing-animation']); // returns error message
  */
 declare function validateAssetAnimations(assetRef: SemanticAssetRef, requiredAnimations: string[]): {
     valid: boolean;
@@ -770,16 +856,46 @@ declare const EntitySchema: z.ZodObject<{
     } | undefined;
 }>;
 /**
- * Derive collection name from entity.
- * Only persistent entities have collections.
+ * Derives the collection name for a persistent entity.
+ *
+ * Generates the database collection name by converting the entity name
+ * to lowercase and adding an 's' suffix (simple pluralization).
+ * Returns undefined for non-persistent entities (runtime/singleton).
+ *
+ * @param {OrbitalEntity} entity - Entity to derive collection name for
+ * @returns {string | undefined} Collection name or undefined for non-persistent entities
+ *
+ * @example
+ * deriveCollection({ name: 'User', persistence: 'persistent' }); // returns 'users'
+ * deriveCollection({ name: 'Task', persistence: 'runtime' }); // returns undefined
  */
 declare function deriveCollection(entity: OrbitalEntity): string | undefined;
 /**
- * Check if entity is runtime-only (not persisted).
+ * Checks if an entity is runtime-only (not persisted).
+ *
+ * Type guard to determine if an entity exists only at runtime
+ * and is not stored in the database.
+ *
+ * @param {OrbitalEntity} entity - Entity to check
+ * @returns {boolean} True if entity is runtime-only, false otherwise
+ *
+ * @example
+ * isRuntimeEntity({ persistence: 'runtime' }); // returns true
+ * isRuntimeEntity({ persistence: 'persistent' }); // returns false
  */
 declare function isRuntimeEntity(entity: OrbitalEntity): boolean;
 /**
- * Check if entity is a singleton.
+ * Checks if an entity is a singleton.
+ *
+ * Type guard to determine if an entity has a single global instance
+ * rather than multiple records in a collection.
+ *
+ * @param {OrbitalEntity} entity - Entity to check
+ * @returns {boolean} True if entity is a singleton, false otherwise
+ *
+ * @example
+ * isSingletonEntity({ persistence: 'singleton' }); // returns true
+ * isSingletonEntity({ persistence: 'persistent' }); // returns false
  */
 declare function isSingletonEntity(entity: OrbitalEntity): boolean;
 
@@ -1199,6 +1315,19 @@ declare const EffectSchema: z.ZodEffects<z.ZodArray<z.ZodUnknown, "many">, unkno
 type EffectInput = z.input<typeof EffectSchema>;
 /**
  * Type guard to check if a value is a valid Effect (S-expression).
+ *
+ * Validates that a value conforms to the Effect structure. Effects are
+ * represented as arrays where the first element is a string (effect type)
+ * and subsequent elements are parameters. Used for runtime validation
+ * of effect structures.
+ *
+ * @param {unknown} value - Value to check
+ * @returns {boolean} True if value is a valid Effect, false otherwise
+ *
+ * @example
+ * isEffect(['set', '@entity.health', 100]); // returns true
+ * isEffect('not-an-effect'); // returns false
+ * isEffect([]); // returns false
  */
 declare function isEffect(value: unknown): value is Effect;
 /**
@@ -1206,18 +1335,51 @@ declare function isEffect(value: unknown): value is Effect;
  */
 declare const isSExprEffect: typeof isEffect;
 /**
- * Create a set effect
- * @example ["set", "@entity.health", 100]
+ * Creates a set effect for state updates.
+ *
+ * Generates an effect that sets a binding to a value. Used in state
+ * machine transitions to update entity fields, UI state, or other
+ * mutable data.
+ *
+ * @param {string} binding - Target binding (e.g., '@entity.health')
+ * @param {SExpr} value - Value to set (can be literal or expression)
+ * @returns {Effect} Set effect array
+ *
+ * @example
+ * set('@entity.health', 100); // returns ["set", "@entity.health", 100]
+ * set('@state.loading', false); // returns ["set", "@state.loading", false]
  */
 declare function set(binding: string, value: SExpr): Effect;
 /**
- * Create an emit effect
- * @example ["emit", "PLAYER_DIED", { "playerId": "@entity.id" }]
+ * Creates an emit effect for event dispatching.
+ *
+ * Generates an effect that emits an event with optional payload.
+ * Used in state machine transitions to trigger events that can be
+ * handled by other traits, services, or external systems.
+ *
+ * @param {string} event - Event name to emit
+ * @param {Record<string, unknown>} [payload] - Optional event payload
+ * @returns {Effect} Emit effect array
+ *
+ * @example
+ * emit('PLAYER_DIED', { playerId: '@entity.id' }); // returns ["emit", "PLAYER_DIED", { playerId: "@entity.id" }]
+ * emit('GAME_STARTED'); // returns ["emit", "GAME_STARTED"]
  */
 declare function emit(event: string, payload?: Record<string, unknown>): Effect;
 /**
- * Create a navigate effect
- * @example ["navigate", "/tasks"]
+ * Creates a navigation effect for page routing.
+ *
+ * Generates an effect that navigates to a specified path with optional
+ * parameters. Used in state machine transitions to change pages or
+ * update URL parameters.
+ *
+ * @param {string} path - Target path (e.g., '/tasks')
+ * @param {Record<string, string>} [params] - Optional URL parameters
+ * @returns {NavigateEffect} Navigation effect array
+ *
+ * @example
+ * navigate('/tasks'); // returns ["navigate", "/tasks"]
+ * navigate('/user', { id: '123' }); // returns ["navigate", "/user", { id: "123" }]
  */
 declare function navigate(path: string): NavigateEffect;
 declare function navigate(path: string, params: Record<string, string>): NavigateEffect;
@@ -1664,8 +1826,8 @@ type StateMachineInput = z.input<typeof StateMachineSchema>;
  * Circuit events are user-defined events that participate in the closed circuit pattern.
  * Internal/system events start with underscore (e.g., _INIT, _TICK, _TIMER).
  *
- * @param event - Event name to check
- * @returns true if event is a circuit event (doesn't start with underscore)
+ * @param {string} event - Event name to check
+ * @returns {boolean} true if event is a circuit event (doesn't start with underscore)
  *
  * @example
  * isCircuitEvent('CREATE') // true
@@ -3188,17 +3350,65 @@ declare const TraitRefSchema: z.ZodUnion<[z.ZodString, z.ZodObject<{
 /**
  * Check if a trait ref is an inline Trait definition
  */
+/**
+ * Checks if a trait reference is an inline trait definition.
+ *
+ * Type guard to determine if a TraitRef is an inline trait object
+ * (with 'name' property) rather than a string reference or object reference.
+ *
+ * @param {TraitRef} traitRef - Trait reference to check
+ * @returns {boolean} True if traitRef is an inline trait, false otherwise
+ *
+ * @example
+ * isInlineTrait({ name: 'MyTrait' }); // returns true (inline)
+ * isInlineTrait('MyTrait'); // returns false (string reference)
+ * isInlineTrait({ ref: 'MyTrait' }); // returns false (object reference)
+ */
 declare function isInlineTrait(traitRef: TraitRef): traitRef is Trait;
 /**
- * Get trait name from a trait reference
+ * Extracts the trait name from a trait reference.
+ *
+ * Handles all trait reference formats (string, inline object, object reference)
+ * and returns the canonical trait name.
+ *
+ * @param {TraitRef} traitRef - Trait reference to extract name from
+ * @returns {string} Trait name
+ *
+ * @example
+ * getTraitName('MyTrait'); // returns 'MyTrait'
+ * getTraitName({ name: 'MyTrait' }); // returns 'MyTrait'
+ * getTraitName({ ref: 'MyTrait' }); // returns 'MyTrait'
  */
 declare function getTraitName(traitRef: TraitRef): string;
 /**
- * Get trait config from a trait reference
+ * Extracts the configuration from a trait reference.
+ *
+ * Returns the configuration object for trait references that support it
+ * (object references with 'config' property). Returns undefined for
+ * string references and inline traits.
+ *
+ * @param {TraitRef} traitRef - Trait reference to extract config from
+ * @returns {Record<string, unknown> | undefined} Trait configuration or undefined
+ *
+ * @example
+ * getTraitConfig('MyTrait'); // returns undefined
+ * getTraitConfig({ name: 'MyTrait' }); // returns undefined
+ * getTraitConfig({ ref: 'MyTrait', config: { option: 'value' } }); // returns config object
  */
 declare function getTraitConfig(traitRef: TraitRef): Record<string, unknown> | undefined;
 /**
- * Normalize trait reference to object form
+ * Normalizes a trait reference to object form.
+ *
+ * Converts any trait reference format (string, inline, object) to a
+ * standardized object format with 'ref' and optional 'config' properties.
+ *
+ * @param {TraitRef} traitRef - Trait reference to normalize
+ * @returns {{ ref: string; config?: Record<string, unknown> }} Normalized trait reference
+ *
+ * @example
+ * normalizeTraitRef('MyTrait'); // returns { ref: 'MyTrait' }
+ * normalizeTraitRef({ name: 'MyTrait' }); // returns { ref: 'MyTrait' }
+ * normalizeTraitRef({ ref: 'MyTrait', config: {...} }); // returns original
  */
 declare function normalizeTraitRef(traitRef: TraitRef): {
     ref: string;
@@ -4281,7 +4491,17 @@ declare const ThemeDefinitionSchema: z.ZodObject<{
  */
 type ThemeRef = ThemeDefinition | string;
 /**
- * Check if ThemeRef is a reference string.
+ * Checks if a theme reference is a string.
+ *
+ * Type guard to determine if a theme reference is a string reference
+ * (format: "Alias.theme") rather than an inline theme definition.
+ *
+ * @param {ThemeRef} theme - Theme reference to check
+ * @returns {boolean} True if theme is a string reference, false otherwise
+ *
+ * @example
+ * isThemeReference("Ocean.theme"); // returns true
+ * isThemeReference({ name: "ocean", colors: {...} }); // returns false
  */
 declare function isThemeReference(theme: ThemeRef): theme is string;
 /**
@@ -4883,7 +5103,17 @@ declare const ServiceDefinitionSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObj
  */
 type ServiceRef = ServiceDefinition | string;
 /**
- * Check if ServiceRef is a reference string.
+ * Checks if a service reference is a string.
+ *
+ * Type guard to determine if a service reference is a string reference
+ * (format: "Alias.services.ServiceName") rather than an inline service definition.
+ *
+ * @param {ServiceRef} service - Service reference to check
+ * @returns {boolean} True if service is a string reference, false otherwise
+ *
+ * @example
+ * isServiceReference("Weather.services.openweather"); // returns true
+ * isServiceReference({ name: "weather", type: "rest" }); // returns false
  */
 declare function isServiceReference(service: ServiceRef): service is string;
 /**
@@ -5018,23 +5248,62 @@ declare const ServiceRefSchema: z.ZodUnion<[z.ZodDiscriminatedUnion<"type", [z.Z
     env?: Record<string, string> | undefined;
 }>]>, z.ZodString]>;
 /**
- * Parse a service reference.
- * @returns { alias, serviceName } or null if not a valid reference
+ * Parses a service reference into its components.
+ *
+ * Extracts the alias and service name from a service reference string
+ * in format "Alias.services.ServiceName". Returns null if not a valid reference.
+ *
+ * @param {string} ref - Service reference string
+ * @returns {{ alias: string; serviceName: string } | null} Parsed components or null
+ *
+ * @example
+ * parseServiceRef("Weather.services.openweather"); // returns { alias: "Weather", serviceName: "openweather" }
+ * parseServiceRef("invalid"); // returns null
  */
 declare function parseServiceRef(ref: string): {
     alias: string;
     serviceName: string;
 } | null;
 /**
- * Check if a service definition is a REST service.
+ * Checks if a service definition is a REST service.
+ *
+ * Type guard to determine if a service definition represents a REST API service.
+ * Used for service type discrimination and validation.
+ *
+ * @param {ServiceDefinition} service - Service definition to check
+ * @returns {boolean} True if service is a REST service, false otherwise
+ *
+ * @example
+ * isRestService({ name: "weather", type: "rest", baseUrl: "..." }); // returns true
+ * isRestService({ name: "chat", type: "socket" }); // returns false
  */
 declare function isRestService(service: ServiceDefinition): service is RestServiceDef;
 /**
- * Check if a service definition is a Socket service.
+ * Checks if a service definition is a Socket service.
+ *
+ * Type guard to determine if a service definition represents a WebSocket service.
+ * Used for service type discrimination and validation.
+ *
+ * @param {ServiceDefinition} service - Service definition to check
+ * @returns {boolean} True if service is a Socket service, false otherwise
+ *
+ * @example
+ * isSocketService({ name: "chat", type: "socket", url: "wss://..." }); // returns true
+ * isSocketService({ name: "weather", type: "rest" }); // returns false
  */
 declare function isSocketService(service: ServiceDefinition): service is SocketServiceDef;
 /**
- * Check if a service definition is an MCP service.
+ * Checks if a service definition is an MCP service.
+ *
+ * Type guard to determine if a service definition represents an MCP
+ * (Multiplayer Control Protocol) service. Used for service type discrimination.
+ *
+ * @param {ServiceDefinition} service - Service definition to check
+ * @returns {boolean} True if service is an MCP service, false otherwise
+ *
+ * @example
+ * isMcpService({ name: "game", type: "mcp", serverUrl: "..." }); // returns true
+ * isMcpService({ name: "chat", type: "socket" }); // returns false
  */
 declare function isMcpService(service: ServiceDefinition): service is McpServiceDef;
 /**
@@ -5109,7 +5378,20 @@ declare const UseDeclarationSchema: z.ZodObject<{
  */
 type EntityRef = Entity | string;
 /**
- * Check if EntityRef is a reference string.
+ * Checks if an entity reference is a string reference.
+ *
+ * Type guard to determine if an EntityRef is a string reference
+ * (format: "Alias.entity") rather than an inline entity definition.
+ *
+ * @param {EntityRef} entity - Entity reference to check
+ * @returns {boolean} True if entity is a string reference, false if inline definition
+ *
+ * @example
+ * const ref1 = "User.entity"; // string reference
+ * const ref2 = { name: "User", fields: [...] }; // inline definition
+ *
+ * isEntityReference(ref1); // returns true
+ * isEntityReference(ref2); // returns false
  */
 declare function isEntityReference(entity: EntityRef): entity is string;
 /**
@@ -5215,15 +5497,56 @@ interface PageRefObject {
  */
 type PageRef = Page | string | PageRefObject;
 /**
- * Check if PageRef is a reference string.
+ * Checks if a page reference is a string reference.
+ *
+ * Type guard to determine if a PageRef is a simple string reference
+ * (format: "Alias.pages.PageName") rather than an inline page definition or object reference.
+ *
+ * @param {PageRef} page - Page reference to check
+ * @returns {boolean} True if page is a string reference, false otherwise
+ *
+ * @example
+ * const ref1 = "User.pages.Profile"; // string reference
+ * const ref2 = { name: "Dashboard", path: "/" }; // inline definition
+ *
+ * isPageReferenceString(ref1); // returns true
+ * isPageReferenceString(ref2); // returns false
  */
 declare function isPageReferenceString(page: PageRef): page is string;
 /**
- * Check if PageRef is a reference object.
+ * Checks if a page reference is a reference object.
+ *
+ * Type guard to determine if a PageRef is an object reference
+ * with a 'ref' property rather than an inline page definition.
+ *
+ * @param {PageRef} page - Page reference to check
+ * @returns {boolean} True if page is a reference object, false otherwise
+ *
+ * @example
+ * const ref1 = { ref: "User.pages.Profile", path: "/custom" }; // reference object
+ * const ref2 = { name: "Dashboard", path: "/" }; // inline definition
+ *
+ * isPageReferenceObject(ref1); // returns true
+ * isPageReferenceObject(ref2); // returns false
  */
 declare function isPageReferenceObject(page: PageRef): page is PageRefObject;
 /**
- * Check if PageRef is a reference (string or object).
+ * Checks if a page reference is any type of reference.
+ *
+ * Type guard to determine if a PageRef is a reference (string or object)
+ * rather than an inline page definition.
+ *
+ * @param {PageRef} page - Page reference to check
+ * @returns {boolean} True if page is a reference, false if inline definition
+ *
+ * @example
+ * const ref1 = "User.pages.Profile"; // string reference
+ * const ref2 = { ref: "User.pages.Profile", path: "/custom" }; // object reference
+ * const ref3 = { name: "Dashboard", path: "/" }; // inline definition
+ *
+ * isPageReference(ref1); // returns true
+ * isPageReference(ref2); // returns true
+ * isPageReference(ref3); // returns false
  */
 declare function isPageReference(page: PageRef): page is string | PageRefObject;
 /**
@@ -5295,27 +5618,64 @@ declare const PageRefSchema: z.ZodUnion<[z.ZodObject<{
     path?: string | undefined;
 }>]>;
 /**
- * Check if a trait reference is an imported reference (has Alias.traits. prefix)
+ * Checks if a trait reference is an imported reference.
+ *
+ * Determines if a trait reference uses the imported format
+ * "Alias.traits.TraitName" rather than a simple "TraitName".
+ *
+ * @param {string} ref - Trait reference to check
+ * @returns {boolean} True if reference is imported format, false otherwise
+ *
+ * @example
+ * isImportedTraitRef("User.traits.Profile"); // returns true
+ * isImportedTraitRef("Profile"); // returns false
  */
 declare function isImportedTraitRef(ref: string): boolean;
 /**
- * Parse an imported trait reference.
- * @returns { alias, traitName } or null if not an imported ref
+ * Parses an imported trait reference.
+ *
+ * Extracts the alias and trait name from an imported trait reference
+ * in format "Alias.traits.TraitName". Returns null if not a valid imported reference.
+ *
+ * @param {string} ref - Trait reference to parse
+ * @returns {{ alias: string; traitName: string } | null} Parsed reference or null
+ *
+ * @example
+ * parseImportedTraitRef("User.traits.Profile"); // returns { alias: "User", traitName: "Profile" }
+ * parseImportedTraitRef("Profile"); // returns null
  */
 declare function parseImportedTraitRef(ref: string): {
     alias: string;
     traitName: string;
 } | null;
 /**
- * Parse an entity reference.
- * @returns { alias } or null if not a valid reference
+ * Parses an entity reference.
+ *
+ * Extracts the alias from an entity reference in format "Alias.entity".
+ * Returns null if not a valid entity reference.
+ *
+ * @param {string} ref - Entity reference to parse
+ * @returns {{ alias: string } | null} Parsed reference or null
+ *
+ * @example
+ * parseEntityRef("User.entity"); // returns { alias: "User" }
+ * parseEntityRef("User"); // returns null
  */
 declare function parseEntityRef(ref: string): {
     alias: string;
 } | null;
 /**
- * Parse a page reference.
- * @returns { alias, pageName } or null if not a valid reference
+ * Parses a page reference.
+ *
+ * Extracts the alias and page name from a page reference
+ * in format "Alias.pages.PageName". Returns null if not a valid page reference.
+ *
+ * @param {string} ref - Page reference to parse
+ * @returns {{ alias: string; pageName: string } | null} Parsed reference or null
+ *
+ * @example
+ * parsePageRef("User.pages.Profile"); // returns { alias: "User", pageName: "Profile" }
+ * parsePageRef("Profile"); // returns null
  */
 declare function parsePageRef(ref: string): {
     alias: string;
@@ -13320,11 +13680,50 @@ declare const OrbitalSchemaSchema: z.ZodObject<{
     }> | undefined;
 }>;
 /**
- * Parse an OrbitalSchema with Zod validation
+ * Parses raw data into a validated OrbitalSchema.
+ *
+ * Uses Zod validation to ensure the data conforms to the OrbitalSchema structure.
+ * Throws a ZodError if validation fails. For safe parsing that doesn't throw,
+ * use `safeParseOrbitalSchema()` instead.
+ *
+ * @param {unknown} data - Raw data to parse (typically JSON)
+ * @returns {OrbitalSchema} Validated orbital schema
+ * @throws {z.ZodError} If data doesn't match OrbitalSchema structure
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const schema = parseOrbitalSchema(jsonData);
+ *   console.log('Valid schema:', schema.name);
+ * } catch (error) {
+ *   console.error('Invalid schema:', error);
+ * }
+ * ```
+ *
+ * @see safeParseOrbitalSchema
  */
 declare function parseOrbitalSchema(data: unknown): OrbitalSchema;
 /**
- * Safe parse an OrbitalSchema
+ * Safely parses raw data into a validated OrbitalSchema without throwing.
+ *
+ * Uses Zod's safeParse method to validate data and return a result object
+ * instead of throwing errors. This is useful for form validation and
+ * user input handling where you want to gracefully handle invalid data.
+ *
+ * @param {unknown} data - Raw data to parse (typically JSON)
+ * @returns {z.SafeParseReturnType<OrbitalSchema, OrbitalSchema>} Parse result with success/status
+ *
+ * @example
+ * ```typescript
+ * const result = safeParseOrbitalSchema(jsonData);
+ * if (result.success) {
+ *   console.log('Valid schema:', result.data.name);
+ * } else {
+ *   console.error('Validation errors:', result.error);
+ * }
+ * ```
+ *
+ * @see parseOrbitalSchema
  */
 declare function safeParseOrbitalSchema(data: unknown): z.SafeParseReturnType<{
     name: string;