@almadar/std 1.0.0

package/dist/behaviors/types.d.ts

@@ -0,0 +1,179 @@
+import { SExpr, RequiredField } from '@almadar/core/types';
+
+/**
+ * Standard Behaviors Types
+ *
+ * Standard Behaviors are reusable Traits with a `std/` naming convention.
+ * They use a more flexible state machine format optimized for authoring.
+ *
+ * ARCHITECTURE: Behaviors ARE Traits conceptually. They use:
+ * - stateMachine: BehaviorStateMachine (flexible states, events, transitions)
+ * - ticks: BehaviorTick[] (frame-by-frame execution for games)
+ * - dataEntities: BehaviorDataEntity[] (runtime state)
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Categories of Standard Behaviors
+ */
+declare const BEHAVIOR_CATEGORIES: readonly ["ui-interaction", "data-management", "async", "feedback", "game-core", "game-entity", "game-ui"];
+type BehaviorCategory = (typeof BEHAVIOR_CATEGORIES)[number];
+type FieldType = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'entity' | 'slot' | 'pattern' | 'event' | 'action[]';
+interface ConfigField {
+    name: string;
+    type: FieldType;
+    description: string;
+    default?: unknown;
+    enum?: string[];
+}
+/**
+ * State definition - can be string or object
+ */
+interface BehaviorState {
+    name: string;
+    isInitial?: boolean;
+    isFinal?: boolean;
+    description?: string;
+}
+/**
+ * Event definition - simplified, only key required
+ */
+interface BehaviorEvent {
+    key: string;
+    name?: string;
+    description?: string;
+    payload?: Record<string, unknown>;
+}
+/**
+ * Transition definition - flexible from/to
+ */
+interface BehaviorTransition {
+    /** Source state(s) - string, '*' for any, or array */
+    from?: string | string[] | '*';
+    /** Target state - optional for self-transitions */
+    to?: string;
+    /** Event that triggers this transition */
+    event: string;
+    /** Guard condition (S-expression) */
+    guard?: SExpr;
+    /** Effects to execute (S-expressions) */
+    effects?: SExpr[];
+}
+/**
+ * State machine for behaviors - more flexible than core StateMachine
+ */
+interface BehaviorStateMachine {
+    initial: string;
+    states: (string | BehaviorState)[];
+    events: (string | BehaviorEvent)[];
+    transitions: BehaviorTransition[];
+    guards?: Array<{
+        name: string;
+        condition: SExpr;
+        description?: string;
+    }>;
+}
+interface BehaviorTick {
+    name: string;
+    description?: string;
+    priority?: number;
+    interval: 'frame' | number;
+    appliesTo?: string[];
+    guard?: SExpr;
+    effects: SExpr[];
+}
+interface BehaviorEntityField {
+    name: string;
+    type: string;
+    default?: unknown;
+    required?: boolean;
+    description?: string;
+}
+interface BehaviorDataEntity {
+    name: string;
+    runtime?: boolean;
+    singleton?: boolean;
+    fields: BehaviorEntityField[];
+    description?: string;
+}
+interface ItemAction {
+    label: string;
+    event?: string;
+    navigatesTo?: string;
+    placement?: 'row' | 'bulk' | 'card' | 'footer' | 'header';
+    variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
+    showWhen?: SExpr | string;
+}
+/**
+ * Configuration schema for documentation and IDE hints
+ */
+interface BehaviorConfig {
+    required: ConfigField[];
+    optional: ConfigField[];
+}
+/**
+ * Standard Behavior definition
+ */
+interface StandardBehavior {
+    /** Behavior identifier (e.g., 'std/List', 'std/Form') */
+    name: string;
+    /** Category for organization */
+    category: BehaviorCategory;
+    /** Human-readable description */
+    description: string;
+    /** When to use this behavior */
+    suggestedFor?: string[];
+    /** Configuration schema for IDE hints */
+    configSchema?: BehaviorConfig;
+    /** State machine definition */
+    stateMachine?: BehaviorStateMachine;
+    /** Required fields from linked entity */
+    requiredFields?: RequiredField[];
+    /** Runtime data entities */
+    dataEntities?: BehaviorDataEntity[];
+    /** Frame-by-frame execution */
+    ticks?: BehaviorTick[];
+    /** Cross-behavior event listeners */
+    listens?: Array<{
+        event: string;
+        triggers: string;
+        guard?: SExpr;
+    }>;
+    /** Initial effects on behavior activation */
+    initialEffects?: SExpr[];
+}
+/**
+ * Behavior metadata for quick lookup
+ */
+interface BehaviorMetadata {
+    name: string;
+    category: BehaviorCategory;
+    description: string;
+    suggestedFor: string[];
+    states: string[];
+    events: string[];
+    tickCount: number;
+    transitionCount: number;
+    hasDataEntities: boolean;
+}
+declare function isBehaviorCategory(value: string): value is BehaviorCategory;
+declare function isGameBehaviorCategory(category: BehaviorCategory): boolean;
+/**
+ * Extract metadata from a StandardBehavior
+ */
+declare function getBehaviorMetadata(behavior: StandardBehavior): BehaviorMetadata;
+/**
+ * Validate behavior structure
+ */
+declare function validateBehaviorStructure(behavior: StandardBehavior): string[];
+/**
+ * Validate behavior events match transitions
+ */
+declare function validateBehaviorEvents(behavior: StandardBehavior): string[];
+/**
+ * Validate behavior states match transitions
+ */
+declare function validateBehaviorStates(behavior: StandardBehavior): string[];
+
+export { BEHAVIOR_CATEGORIES, type BehaviorCategory, type BehaviorConfig, type BehaviorDataEntity, type BehaviorEntityField, type BehaviorEvent, type BehaviorMetadata, type BehaviorState, type BehaviorStateMachine, type BehaviorTick, type BehaviorTransition, type ConfigField, type FieldType, type ItemAction, type StandardBehavior, getBehaviorMetadata, isBehaviorCategory, isGameBehaviorCategory, validateBehaviorEvents, validateBehaviorStates, validateBehaviorStructure };

package/dist/behaviors/types.js

@@ -0,0 +1,111 @@
+// behaviors/types.ts
+var BEHAVIOR_CATEGORIES = [
+  "ui-interaction",
+  // User interface state management
+  "data-management",
+  // Data operations and state
+  "async",
+  // Asynchronous workflows
+  "feedback",
+  // User feedback and confirmations
+  "game-core",
+  // Game loop and systems
+  "game-entity",
+  // Game entity behaviors
+  "game-ui"
+  // Game interface
+];
+function isBehaviorCategory(value) {
+  return BEHAVIOR_CATEGORIES.includes(value);
+}
+function isGameBehaviorCategory(category) {
+  return category.startsWith("game-");
+}
+function getBehaviorMetadata(behavior) {
+  const sm = behavior.stateMachine;
+  const states = (sm?.states || []).map(
+    (s) => typeof s === "string" ? s : s.name
+  );
+  const events = (sm?.events || []).map(
+    (e) => typeof e === "string" ? e : e.key
+  );
+  return {
+    name: behavior.name,
+    category: behavior.category,
+    description: behavior.description || "",
+    suggestedFor: behavior.suggestedFor || [],
+    states,
+    events,
+    tickCount: behavior.ticks?.length || 0,
+    transitionCount: sm?.transitions?.length || 0,
+    hasDataEntities: (behavior.dataEntities?.length || 0) > 0
+  };
+}
+function validateBehaviorStructure(behavior) {
+  const errors = [];
+  if (!behavior.name) {
+    errors.push("Behavior must have a name");
+  }
+  if (!behavior.name.startsWith("std/")) {
+    errors.push(`Behavior name should start with 'std/' (got: ${behavior.name})`);
+  }
+  if (!behavior.category) {
+    errors.push("Behavior must have a category");
+  }
+  if (!isBehaviorCategory(behavior.category)) {
+    errors.push(`Invalid category: ${behavior.category}`);
+  }
+  const sm = behavior.stateMachine;
+  if (sm) {
+    if (!sm.states || sm.states.length === 0) {
+      errors.push("State machine must have at least one state");
+    }
+    if (!sm.initial) {
+      errors.push("State machine must have an initial state");
+    }
+  }
+  return errors;
+}
+function validateBehaviorEvents(behavior) {
+  const errors = [];
+  const sm = behavior.stateMachine;
+  if (!sm) return errors;
+  const declaredEvents = new Set(
+    (sm.events || []).map((e) => typeof e === "string" ? e : e.key)
+  );
+  const transitionEvents = new Set(
+    (sm.transitions || []).map((t) => t.event)
+  );
+  for (const event of transitionEvents) {
+    if (event && !declaredEvents.has(event)) {
+      errors.push(`Transition uses undeclared event: ${event}`);
+    }
+  }
+  return errors;
+}
+function validateBehaviorStates(behavior) {
+  const errors = [];
+  const sm = behavior.stateMachine;
+  if (!sm) return errors;
+  const declaredStates = new Set(
+    (sm.states || []).map((s) => typeof s === "string" ? s : s.name)
+  );
+  for (const t of sm.transitions || []) {
+    if (t.from && t.from !== "*") {
+      const fromStates = Array.isArray(t.from) ? t.from : [t.from];
+      for (const state of fromStates) {
+        if (!declaredStates.has(state)) {
+          errors.push(`Transition from undeclared state: ${state}`);
+        }
+      }
+    }
+    if (t.to && !declaredStates.has(t.to)) {
+      errors.push(`Transition to undeclared state: ${t.to}`);
+    }
+  }
+  return errors;
+}
+
+export { BEHAVIOR_CATEGORIES, getBehaviorMetadata, isBehaviorCategory, isGameBehaviorCategory, validateBehaviorEvents, validateBehaviorStates, validateBehaviorStructure };
+//# sourceMappingURL=types.js.map
+//# sourceMappingURL=types.js.map

package/dist/behaviors/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../behaviors/types.ts"],"names":[],"mappings":";AAuBO,IAAM,mBAAA,GAAsB;AAAA,EACjC,gBAAA;AAAA;AAAA,EACA,iBAAA;AAAA;AAAA,EACA,OAAA;AAAA;AAAA,EACA,UAAA;AAAA;AAAA,EACA,WAAA;AAAA;AAAA,EACA,aAAA;AAAA;AAAA,EACA;AAAA;AACF;AAiNO,SAAS,mBAAmB,KAAA,EAA0C;AAC3E,EAAA,OAAO,mBAAA,CAAoB,SAAS,KAAyB,CAAA;AAC/D;AAEO,SAAS,uBAAuB,QAAA,EAAqC;AAC1E,EAAA,OAAO,QAAA,CAAS,WAAW,OAAO,CAAA;AACpC;AAKO,SAAS,oBAAoB,QAAA,EAA8C;AAChF,EAAA,MAAM,KAAK,QAAA,CAAS,YAAA;AAEpB,EAAA,MAAM,MAAA,GAAA,CAAoB,EAAA,EAAI,MAAA,IAAU,EAAC,EAAG,GAAA;AAAA,IAAI,CAAA,CAAA,KAC9C,OAAO,CAAA,KAAM,QAAA,GAAW,IAAI,CAAA,CAAE;AAAA,GAChC;AAEA,EAAA,MAAM,MAAA,GAAA,CAAoB,EAAA,EAAI,MAAA,IAAU,EAAC,EAAG,GAAA;AAAA,IAAI,CAAA,CAAA,KAC9C,OAAO,CAAA,KAAM,QAAA,GAAW,IAAI,CAAA,CAAE;AAAA,GAChC;AAEA,EAAA,OAAO;AAAA,IACL,MAAM,QAAA,CAAS,IAAA;AAAA,IACf,UAAU,QAAA,CAAS,QAAA;AAAA,IACnB,WAAA,EAAa,SAAS,WAAA,IAAe,EAAA;AAAA,IACrC,YAAA,EAAc,QAAA,CAAS,YAAA,IAAgB,EAAC;AAAA,IACxC,MAAA;AAAA,IACA,MAAA;AAAA,IACA,SAAA,EAAW,QAAA,CAAS,KAAA,EAAO,MAAA,IAAU,CAAA;AAAA,IACrC,eAAA,EAAiB,EAAA,EAAI,WAAA,EAAa,MAAA,IAAU,CAAA;AAAA,IAC5C,eAAA,EAAA,CAAkB,QAAA,CAAS,YAAA,EAAc,MAAA,IAAU,CAAA,IAAK;AAAA,GAC1D;AACF;AAKO,SAAS,0BAA0B,QAAA,EAAsC;AAC9E,EAAA,MAAM,SAAmB,EAAC;AAE1B,EAAA,IAAI,CAAC,SAAS,IAAA,EAAM;AAClB,IAAA,MAAA,CAAO,KAAK,2BAA2B,CAAA;AAAA,EACzC;AAEA,EAAA,IAAI,CAAC,QAAA,CAAS,IAAA,CAAK,UAAA,CAAW,MAAM,CAAA,EAAG;AACrC,IAAA,MAAA,CAAO,IAAA,CAAK,CAAA,6CAAA,EAAgD,QAAA,CAAS,IAAI,CAAA,CAAA,CAAG,CAAA;AAAA,EAC9E;AAEA,EAAA,IAAI,CAAC,SAAS,QAAA,EAAU;AACtB,IAAA,MAAA,CAAO,KAAK,+BAA+B,CAAA;AAAA,EAC7C;AAEA,EAAA,IAAI,CAAC,kBAAA,CAAmB,QAAA,CAAS,QAAQ,CAAA,EAAG;AAC1C,IAAA,MAAA,CAAO,IAAA,CAAK,CAAA,kBAAA,EAAqB,QAAA,CAAS,QAAQ,CAAA,CAAE,CAAA;AAAA,EACtD;AAEA,EAAA,MAAM,KAAK,QAAA,CAAS,YAAA;AACpB,EAAA,IAAI,EAAA,EAAI;AACN,IAAA,IAAI,CAAC,EAAA,CAAG,MAAA,IAAU,EAAA,CAAG,MAAA,CAAO,WAAW,CAAA,EAAG;AACxC,MAAA,MAAA,CAAO,KAAK,4CAA4C,CAAA;AAAA,IAC1D;AAEA,IAAA,IAAI,CAAC,GAAG,OAAA,EAAS;AACf,MAAA,MAAA,CAAO,KAAK,0CAA0C,CAAA;AAAA,IACxD;AAAA,EACF;AAEA,EAAA,OAAO,MAAA;AACT;AAKO,SAAS,uBAAuB,QAAA,EAAsC;AAC3E,EAAA,MAAM,SAAmB,EAAC;AAC1B,EAAA,MAAM,KAAK,QAAA,CAAS,YAAA;AACpB,EAAA,IAAI,CAAC,IAAI,OAAO,MAAA;AAEhB,EAAA,MAAM,iBAAiB,IAAI,GAAA;AAAA,IAAA,CACxB,EAAA,CAAG,MAAA,IAAU,EAAC,EAAG,GAAA,CAAI,CAAA,CAAA,KAAK,OAAO,CAAA,KAAM,QAAA,GAAW,CAAA,GAAI,CAAA,CAAE,GAAG;AAAA,GAC9D;AAEA,EAAA,MAAM,mBAAmB,IAAI,GAAA;AAAA,IAAA,CAC1B,GAAG,WAAA,IAAe,IAAI,GAAA,CAAI,CAAA,CAAA,KAAK,EAAE,KAAK;AAAA,GACzC;AAEA,EAAA,KAAA,MAAW,SAAS,gBAAA,EAAkB;AACpC,IAAA,IAAI,KAAA,IAAS,CAAC,cAAA,CAAe,GAAA,CAAI,KAAK,CAAA,EAAG;AACvC,MAAA,MAAA,CAAO,IAAA,CAAK,CAAA,kCAAA,EAAqC,KAAK,CAAA,CAAE,CAAA;AAAA,IAC1D;AAAA,EACF;AAEA,EAAA,OAAO,MAAA;AACT;AAKO,SAAS,uBAAuB,QAAA,EAAsC;AAC3E,EAAA,MAAM,SAAmB,EAAC;AAC1B,EAAA,MAAM,KAAK,QAAA,CAAS,YAAA;AACpB,EAAA,IAAI,CAAC,IAAI,OAAO,MAAA;AAEhB,EAAA,MAAM,iBAAiB,IAAI,GAAA;AAAA,IAAA,CACxB,EAAA,CAAG,MAAA,IAAU,EAAC,EAAG,GAAA,CAAI,CAAA,CAAA,KAAK,OAAO,CAAA,KAAM,QAAA,GAAW,CAAA,GAAI,CAAA,CAAE,IAAI;AAAA,GAC/D;AAEA,EAAA,KAAA,MAAW,CAAA,IAAK,EAAA,CAAG,WAAA,IAAe,EAAC,EAAG;AAEpC,IAAA,IAAI,CAAA,CAAE,IAAA,IAAQ,CAAA,CAAE,IAAA,KAAS,GAAA,EAAK;AAC5B,MAAA,MAAM,UAAA,GAAa,KAAA,CAAM,OAAA,CAAQ,CAAA,CAAE,IAAI,IAAI,CAAA,CAAE,IAAA,GAAO,CAAC,CAAA,CAAE,IAAI,CAAA;AAC3D,MAAA,KAAA,MAAW,SAAS,UAAA,EAAY;AAC9B,QAAA,IAAI,CAAC,cAAA,CAAe,GAAA,CAAI,KAAK,CAAA,EAAG;AAC9B,UAAA,MAAA,CAAO,IAAA,CAAK,CAAA,kCAAA,EAAqC,KAAK,CAAA,CAAE,CAAA;AAAA,QAC1D;AAAA,MACF;AAAA,IACF;AAGA,IAAA,IAAI,EAAE,EAAA,IAAM,CAAC,eAAe,GAAA,CAAI,CAAA,CAAE,EAAE,CAAA,EAAG;AACrC,MAAA,MAAA,CAAO,IAAA,CAAK,CAAA,gCAAA,EAAmC,CAAA,CAAE,EAAE,CAAA,CAAE,CAAA;AAAA,IACvD;AAAA,EACF;AAEA,EAAA,OAAO,MAAA;AACT","file":"types.js","sourcesContent":["/**\n * Standard Behaviors Types\n *\n * Standard Behaviors are reusable Traits with a `std/` naming convention.\n * They use a more flexible state machine format optimized for authoring.\n *\n * ARCHITECTURE: Behaviors ARE Traits conceptually. They use:\n * - stateMachine: BehaviorStateMachine (flexible states, events, transitions)\n * - ticks: BehaviorTick[] (frame-by-frame execution for games)\n * - dataEntities: BehaviorDataEntity[] (runtime state)\n *\n * @packageDocumentation\n */\n\nimport type { SExpr, RequiredField } from '@almadar/core/types';\n\n// ============================================================================\n// Behavior Categories\n// ============================================================================\n\n/**\n * Categories of Standard Behaviors\n */\nexport const BEHAVIOR_CATEGORIES = [\n  'ui-interaction',   // User interface state management\n  'data-management',  // Data operations and state\n  'async',            // Asynchronous workflows\n  'feedback',         // User feedback and confirmations\n  'game-core',        // Game loop and systems\n  'game-entity',      // Game entity behaviors\n  'game-ui',          // Game interface\n] as const;\n\nexport type BehaviorCategory = (typeof BEHAVIOR_CATEGORIES)[number];\n\n// ============================================================================\n// Config Field Types (for IDE hints and documentation)\n// ============================================================================\n\nexport type FieldType =\n  | 'string'\n  | 'number'\n  | 'boolean'\n  | 'array'\n  | 'object'\n  | 'entity'\n  | 'slot'\n  | 'pattern'\n  | 'event'\n  | 'action[]';\n\nexport interface ConfigField {\n  name: string;\n  type: FieldType;\n  description: string;\n  default?: unknown;\n  enum?: string[];\n}\n\n// ============================================================================\n// Behavior State Machine Types (flexible for authoring)\n// ============================================================================\n\n/**\n * State definition - can be string or object\n */\nexport interface BehaviorState {\n  name: string;\n  isInitial?: boolean;\n  isFinal?: boolean;\n  description?: string;\n}\n\n/**\n * Event definition - simplified, only key required\n */\nexport interface BehaviorEvent {\n  key: string;\n  name?: string;\n  description?: string;\n  payload?: Record<string, unknown>;\n}\n\n/**\n * Transition definition - flexible from/to\n */\nexport interface BehaviorTransition {\n  /** Source state(s) - string, '*' for any, or array */\n  from?: string | string[] | '*';\n  /** Target state - optional for self-transitions */\n  to?: string;\n  /** Event that triggers this transition */\n  event: string;\n  /** Guard condition (S-expression) */\n  guard?: SExpr;\n  /** Effects to execute (S-expressions) */\n  effects?: SExpr[];\n}\n\n/**\n * State machine for behaviors - more flexible than core StateMachine\n */\nexport interface BehaviorStateMachine {\n  initial: string;\n  states: (string | BehaviorState)[];\n  events: (string | BehaviorEvent)[];\n  transitions: BehaviorTransition[];\n  guards?: Array<{\n    name: string;\n    condition: SExpr;\n    description?: string;\n  }>;\n}\n\n// ============================================================================\n// Behavior Tick (for frame-by-frame execution)\n// ============================================================================\n\nexport interface BehaviorTick {\n  name: string;\n  description?: string;\n  priority?: number;\n  interval: 'frame' | number;\n  appliesTo?: string[];\n  guard?: SExpr;\n  effects: SExpr[];\n}\n\n// ============================================================================\n// Behavior Data Entity (runtime state)\n// ============================================================================\n\nexport interface BehaviorEntityField {\n  name: string;\n  type: string;\n  default?: unknown;\n  required?: boolean;\n  description?: string;\n}\n\nexport interface BehaviorDataEntity {\n  name: string;\n  runtime?: boolean;\n  singleton?: boolean;\n  fields: BehaviorEntityField[];\n  description?: string;\n}\n\n// ============================================================================\n// Item Action (for render_ui props)\n// ============================================================================\n\nexport interface ItemAction {\n  label: string;\n  event?: string;\n  navigatesTo?: string;\n  placement?: 'row' | 'bulk' | 'card' | 'footer' | 'header';\n  variant?: 'primary' | 'secondary' | 'ghost' | 'danger';\n  showWhen?: SExpr | string;\n}\n\n// ============================================================================\n// Standard Behavior Interface\n// ============================================================================\n\n/**\n * Configuration schema for documentation and IDE hints\n */\nexport interface BehaviorConfig {\n  required: ConfigField[];\n  optional: ConfigField[];\n}\n\n/**\n * Standard Behavior definition\n */\nexport interface StandardBehavior {\n  /** Behavior identifier (e.g., 'std/List', 'std/Form') */\n  name: string;\n\n  /** Category for organization */\n  category: BehaviorCategory;\n\n  /** Human-readable description */\n  description: string;\n\n  // ========== Documentation Extensions ==========\n\n  /** When to use this behavior */\n  suggestedFor?: string[];\n\n  /** Configuration schema for IDE hints */\n  configSchema?: BehaviorConfig;\n\n  // ========== State Machine ==========\n\n  /** State machine definition */\n  stateMachine?: BehaviorStateMachine;\n\n  // ========== Trait Features ==========\n\n  /** Required fields from linked entity */\n  requiredFields?: RequiredField[];\n\n  /** Runtime data entities */\n  dataEntities?: BehaviorDataEntity[];\n\n  /** Frame-by-frame execution */\n  ticks?: BehaviorTick[];\n\n  /** Cross-behavior event listeners */\n  listens?: Array<{\n    event: string;\n    triggers: string;\n    guard?: SExpr;\n  }>;\n\n  /** Initial effects on behavior activation */\n  initialEffects?: SExpr[];\n}\n\n/**\n * Behavior metadata for quick lookup\n */\nexport interface BehaviorMetadata {\n  name: string;\n  category: BehaviorCategory;\n  description: string;\n  suggestedFor: string[];\n  states: string[];\n  events: string[];\n  tickCount: number;\n  transitionCount: number;\n  hasDataEntities: boolean;\n}\n\n// ============================================================================\n// Helper Functions\n// ============================================================================\n\nexport function isBehaviorCategory(value: string): value is BehaviorCategory {\n  return BEHAVIOR_CATEGORIES.includes(value as BehaviorCategory);\n}\n\nexport function isGameBehaviorCategory(category: BehaviorCategory): boolean {\n  return category.startsWith('game-');\n}\n\n/**\n * Extract metadata from a StandardBehavior\n */\nexport function getBehaviorMetadata(behavior: StandardBehavior): BehaviorMetadata {\n  const sm = behavior.stateMachine;\n\n  const states: string[] = (sm?.states || []).map(s =>\n    typeof s === 'string' ? s : s.name\n  );\n\n  const events: string[] = (sm?.events || []).map(e =>\n    typeof e === 'string' ? e : e.key\n  );\n\n  return {\n    name: behavior.name,\n    category: behavior.category,\n    description: behavior.description || '',\n    suggestedFor: behavior.suggestedFor || [],\n    states,\n    events,\n    tickCount: behavior.ticks?.length || 0,\n    transitionCount: sm?.transitions?.length || 0,\n    hasDataEntities: (behavior.dataEntities?.length || 0) > 0,\n  };\n}\n\n/**\n * Validate behavior structure\n */\nexport function validateBehaviorStructure(behavior: StandardBehavior): string[] {\n  const errors: string[] = [];\n\n  if (!behavior.name) {\n    errors.push('Behavior must have a name');\n  }\n\n  if (!behavior.name.startsWith('std/')) {\n    errors.push(`Behavior name should start with 'std/' (got: ${behavior.name})`);\n  }\n\n  if (!behavior.category) {\n    errors.push('Behavior must have a category');\n  }\n\n  if (!isBehaviorCategory(behavior.category)) {\n    errors.push(`Invalid category: ${behavior.category}`);\n  }\n\n  const sm = behavior.stateMachine;\n  if (sm) {\n    if (!sm.states || sm.states.length === 0) {\n      errors.push('State machine must have at least one state');\n    }\n\n    if (!sm.initial) {\n      errors.push('State machine must have an initial state');\n    }\n  }\n\n  return errors;\n}\n\n/**\n * Validate behavior events match transitions\n */\nexport function validateBehaviorEvents(behavior: StandardBehavior): string[] {\n  const errors: string[] = [];\n  const sm = behavior.stateMachine;\n  if (!sm) return errors;\n\n  const declaredEvents = new Set(\n    (sm.events || []).map(e => typeof e === 'string' ? e : e.key)\n  );\n\n  const transitionEvents = new Set(\n    (sm.transitions || []).map(t => t.event)\n  );\n\n  for (const event of transitionEvents) {\n    if (event && !declaredEvents.has(event)) {\n      errors.push(`Transition uses undeclared event: ${event}`);\n    }\n  }\n\n  return errors;\n}\n\n/**\n * Validate behavior states match transitions\n */\nexport function validateBehaviorStates(behavior: StandardBehavior): string[] {\n  const errors: string[] = [];\n  const sm = behavior.stateMachine;\n  if (!sm) return errors;\n\n  const declaredStates = new Set(\n    (sm.states || []).map(s => typeof s === 'string' ? s : s.name)\n  );\n\n  for (const t of sm.transitions || []) {\n    // Check 'from' states (allow '*' and arrays)\n    if (t.from && t.from !== '*') {\n      const fromStates = Array.isArray(t.from) ? t.from : [t.from];\n      for (const state of fromStates) {\n        if (!declaredStates.has(state)) {\n          errors.push(`Transition from undeclared state: ${state}`);\n        }\n      }\n    }\n\n    // Check 'to' state (optional)\n    if (t.to && !declaredStates.has(t.to)) {\n      errors.push(`Transition to undeclared state: ${t.to}`);\n    }\n  }\n\n  return errors;\n}\n"]}

package/dist/behaviors/ui-interaction.d.ts

@@ -0,0 +1,36 @@
+import { StandardBehavior } from './types.js';
+import '@almadar/core/types';
+
+/**
+ * UI Interaction Behaviors
+ *
+ * Standard behaviors for common UI interaction patterns.
+ * These use the Trait architecture with stateMachine.
+ *
+ * IMPORTANT: These are GENERATION TEMPLATES for LLMs.
+ * They must use correct syntax:
+ * - render-ui (not render)
+ * - Explicit from states (not '*')
+ * - Valid pattern types (form-section, entity-detail, etc.)
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * std/List - The core behavior for displaying and interacting with entity collections.
+ *
+ * States: Browsing → Creating/Viewing/Editing/Deleting
+ * Implements complete CRUD operations with modal/drawer UI patterns.
+ */
+declare const LIST_BEHAVIOR: StandardBehavior;
+declare const DETAIL_BEHAVIOR: StandardBehavior;
+declare const FORM_BEHAVIOR: StandardBehavior;
+declare const MODAL_BEHAVIOR: StandardBehavior;
+declare const DRAWER_BEHAVIOR: StandardBehavior;
+declare const TABS_BEHAVIOR: StandardBehavior;
+declare const WIZARD_BEHAVIOR: StandardBehavior;
+declare const MASTER_DETAIL_BEHAVIOR: StandardBehavior;
+declare const FILTER_BEHAVIOR: StandardBehavior;
+declare const UI_INTERACTION_BEHAVIORS: StandardBehavior[];
+
+export { DETAIL_BEHAVIOR, DRAWER_BEHAVIOR, FILTER_BEHAVIOR, FORM_BEHAVIOR, LIST_BEHAVIOR, MASTER_DETAIL_BEHAVIOR, MODAL_BEHAVIOR, TABS_BEHAVIOR, UI_INTERACTION_BEHAVIORS, WIZARD_BEHAVIOR };