@almadar/core 2.14.3 → 3.0.0

package/dist/builders.d.ts

@@ -1,5 +1,5 @@
-import { T as TraitEventContract, E as EntityField, a as EntityPersistence, b as EntityRow, O as OrbitalDefinition, c as OrbitalSchema, d as Trait, e as Entity, P as Page } from './schema-BFnZrBhm.js';
-export { C as ComposeBehaviorsInput, a as ComposeBehaviorsResult, E as EventWiringEntry, L as LayoutStrategy, b as applyEventWiring, c as composeBehaviors, d as detectLayoutStrategy } from './compose-behaviors-CQC8hsaL.js';
+import { T as TraitEventContract, E as EntityField, a as EntityPersistence, b as EntityRow, O as OrbitalDefinition, c as OrbitalSchema, d as Trait, e as Entity, P as Page } from './schema-COvHzxfu.js';
+export { C as ComposeBehaviorsInput, a as ComposeBehaviorsResult, E as EventWiringEntry, L as LayoutStrategy, b as applyEventWiring, c as composeBehaviors, d as detectLayoutStrategy } from './compose-behaviors-tUJ7EcaX.js';
 import 'zod';
 import '@almadar/patterns';
 

package/dist/builders.js

@@ -1,66 +1,181 @@
 import { z } from 'zod';
 
-// src/builders/layout-strategy.ts
-function hasSequentialChain(wiring) {
-  if (wiring.length < 2) {
-    return false;
-  }
-  const adjacency = /* @__PURE__ */ new Map();
-  const allTargets = /* @__PURE__ */ new Set();
-  for (const entry of wiring) {
-    let targets = adjacency.get(entry.from);
-    if (!targets) {
-      targets = /* @__PURE__ */ new Set();
-      adjacency.set(entry.from, targets);
-    }
-    targets.add(entry.to);
-    allTargets.add(entry.to);
-  }
-  const roots = [];
-  for (const from of adjacency.keys()) {
-    if (!allTargets.has(from)) {
-      roots.push(from);
-    }
-  }
-  const starts = roots.length > 0 ? roots : [...adjacency.keys()];
-  for (const start of starts) {
-    let current = start;
-    let length = 1;
-    const visited = /* @__PURE__ */ new Set([current]);
-    while (true) {
-      const nexts = adjacency.get(current);
-      if (!nexts || nexts.size === 0) break;
-      let advanced = false;
-      for (const next of nexts) {
-        if (!visited.has(next)) {
-          visited.add(next);
-          current = next;
-          length++;
-          advanced = true;
-          break;
-        }
-      }
-      if (!advanced) break;
-    }
-    if (length >= 3) {
-      return true;
-    }
-  }
-  return false;
-}
-function detectLayoutStrategy(orbitals, eventWiring) {
-  if (eventWiring && eventWiring.length > 0 && hasSequentialChain(eventWiring)) {
-    return "wizard-flow";
-  }
-  const count = orbitals.length;
-  if (count <= 1) {
-    return "single";
-  }
-  if (count <= 4) {
-    return "tabs";
-  }
-  return "sidebar";
-}
+// src/types/orbital.ts
+var FieldTypeSchema = z.enum([
+  "string",
+  "number",
+  "boolean",
+  "date",
+  "timestamp",
+  "datetime",
+  "array",
+  "object",
+  "enum",
+  "relation"
+]);
+var RelationCardinalitySchema = z.enum([
+  "one",
+  "many",
+  "one-to-many",
+  "many-to-one",
+  "many-to-many"
+]);
+var RelationConfigSchema = z.object({
+  entity: z.string().min(1, "Target entity is required"),
+  field: z.string().optional(),
+  cardinality: RelationCardinalitySchema.optional(),
+  onDelete: z.enum(["cascade", "nullify", "restrict"]).optional(),
+  // Legacy compatibility fields
+  foreignKey: z.string().optional(),
+  target: z.string().optional(),
+  type: RelationCardinalitySchema.optional()
+}).transform((data) => {
+  const normalized = {
+    entity: data.entity || data.target || "",
+    cardinality: data.cardinality || data.type,
+    field: data.field,
+    onDelete: data.onDelete
+  };
+  return normalized;
+});
+var FieldFormatSchema = z.enum([
+  "email",
+  "url",
+  "phone",
+  "date",
+  "datetime",
+  "uuid"
+]);
+var EntityFieldSchema = z.lazy(
+  () => z.object({
+    name: z.string().min(1, "Field name is required"),
+    type: FieldTypeSchema,
+    required: z.boolean().optional(),
+    default: z.unknown().optional(),
+    values: z.array(z.string()).optional(),
+    enum: z.array(z.string()).optional(),
+    format: FieldFormatSchema.optional(),
+    min: z.number().optional(),
+    max: z.number().optional(),
+    items: EntityFieldSchema.optional(),
+    relation: RelationConfigSchema.optional()
+  }).refine(
+    (field) => field.type !== "relation" || field.relation !== void 0,
+    { message: 'Relation config is required when type is "relation"', path: ["relation"] }
+  )
+);
+var ENTITY_ROLES = [
+  "player",
+  "enemy",
+  "npc",
+  "item",
+  "tile",
+  "projectile",
+  "effect",
+  "ui",
+  "decoration",
+  "vehicle"
+];
+var EntityRoleSchema = z.enum(ENTITY_ROLES);
+var VISUAL_STYLES = ["pixel", "vector", "hd", "1-bit", "isometric"];
+var VisualStyleSchema = z.enum(VISUAL_STYLES);
+var GAME_TYPES = [
+  "platformer",
+  "roguelike",
+  "top-down",
+  "puzzle",
+  "racing",
+  "card",
+  "board",
+  "shooter",
+  "rpg"
+];
+var GameTypeSchema = z.enum(GAME_TYPES);
+var AnimationDefSchema = z.object({
+  frames: z.union([z.array(z.number()), z.array(z.string())]),
+  fps: z.number().positive(),
+  loop: z.boolean()
+});
+var SemanticAssetRefSchema = z.object({
+  role: EntityRoleSchema,
+  category: z.string().min(1),
+  animations: z.array(z.string()).optional(),
+  style: VisualStyleSchema.optional(),
+  variant: z.string().optional()
+});
+z.object({
+  basePath: z.string(),
+  path: z.string(),
+  tiles: z.array(z.number()).optional(),
+  tileSize: z.number().positive().optional(),
+  files: z.array(z.string()).optional(),
+  animations: z.record(AnimationDefSchema).optional()
+});
+var AssetMappingSchema = z.object({
+  path: z.string(),
+  tiles: z.array(z.number()).optional(),
+  tileSize: z.number().positive().optional(),
+  files: z.array(z.string()).optional(),
+  animations: z.record(AnimationDefSchema).optional()
+});
+z.object({
+  gameType: GameTypeSchema,
+  style: VisualStyleSchema,
+  basePath: z.string(),
+  mappings: z.record(AssetMappingSchema)
+});
+
+// src/types/entity.ts
+var EntityPersistenceSchema = z.enum([
+  "persistent",
+  "runtime",
+  "singleton",
+  "instance",
+  "local"
+]);
+var OrbitalEntitySchema = z.object({
+  name: z.string().min(1, "Entity name is required"),
+  persistence: EntityPersistenceSchema.default("persistent"),
+  collection: z.string().optional(),
+  fields: z.array(EntityFieldSchema).min(1, "At least one field is required"),
+  instances: z.array(z.record(z.unknown())).optional(),
+  timestamps: z.boolean().optional(),
+  softDelete: z.boolean().optional(),
+  description: z.string().optional(),
+  visual_prompt: z.string().optional(),
+  assetRef: SemanticAssetRefSchema.optional()
+});
+var EntitySchema = OrbitalEntitySchema;
+var ViewTypeSchema = z.enum([
+  "list",
+  "detail",
+  "create",
+  "edit",
+  "dashboard",
+  "custom"
+]);
+var PageTraitRefSchema = z.object({
+  ref: z.string().min(1, "Trait ref is required"),
+  linkedEntity: z.string().optional(),
+  config: z.record(z.unknown()).optional()
+});
+z.object({
+  name: z.string().min(1, "Page name is required"),
+  path: z.string().min(1, "Page path is required").startsWith("/", "Path must start with /"),
+  primaryEntity: z.string().min(1, "Primary entity is required"),
+  traits: z.array(PageTraitRefSchema).min(1, "Page must have at least one trait"),
+  title: z.string().optional()
+}).strict();
+var OrbitalPageSchema = z.object({
+  name: z.string().min(1, "Page name is required"),
+  path: z.string().min(1, "Page path is required").startsWith("/", "Path must start with /"),
+  viewType: ViewTypeSchema.optional(),
+  title: z.string().optional(),
+  primaryEntity: z.string().optional(),
+  traits: z.array(PageTraitRefSchema).optional(),
+  isInitial: z.boolean().optional()
+}).strict();
+var PageSchema = OrbitalPageSchema;
 var UI_SLOTS = [
   // App slots
   "main",
@@ -244,6 +359,8 @@ var RequiredFieldSchema = z.object({
 z.object({
   ref: z.string().min(1),
   linkedEntity: z.string().optional(),
+  name: z.string().optional(),
+  events: z.record(z.string(), z.string()).optional(),
   config: z.record(z.record(z.unknown())).optional(),
   appliesTo: z.array(z.string()).optional()
 });
@@ -262,12 +379,14 @@ var TraitSchema = z.object({
   listens: z.array(TraitEventListenerSchema).optional(),
   ui: z.record(z.unknown()).optional()
 });
-z.union([
+var TraitRefSchema = z.union([
   z.string().min(1),
   z.object({
     ref: z.string().min(1),
     config: z.record(z.unknown()).optional(),
-    linkedEntity: z.string().optional()
+    linkedEntity: z.string().optional(),
+    name: z.string().optional(),
+    events: z.record(z.string(), z.string()).optional()
   }),
   TraitSchema
   // Allow inline trait definitions
@@ -275,6 +394,403 @@ z.union([
 function isInlineTrait(traitRef) {
   return typeof traitRef === "object" && "name" in traitRef && !("ref" in traitRef);
 }
+z.enum([
+  "healthcare",
+  "education",
+  "finance",
+  "ecommerce",
+  "real-estate",
+  "logistics",
+  "hospitality",
+  "hr-management",
+  "project-management",
+  "social",
+  "content-management",
+  "iot",
+  "analytics",
+  "game",
+  "custom"
+]);
+var AGENT_DOMAIN_CATEGORIES = [
+  "game",
+  "business",
+  "dashboard",
+  "form",
+  "content",
+  "social",
+  "ecommerce",
+  "workflow"
+];
+var AgentDomainCategorySchema = z.enum([...AGENT_DOMAIN_CATEGORIES]);
+z.enum([
+  "platformer",
+  "shooter",
+  "puzzle",
+  "rpg",
+  "board",
+  "racing",
+  "fighting",
+  "tower-defense",
+  "endless-runner",
+  "simulation",
+  "arcade",
+  "adventure"
+]);
+z.enum(["domain", "system"]);
+z.enum([
+  "pending",
+  "active",
+  "completed",
+  "cancelled",
+  "error",
+  "suspended",
+  "blocked",
+  "domain_workflow",
+  "domain_status",
+  "system_loading",
+  "system_error",
+  "system_idle",
+  "system_editing",
+  "system_confirming"
+]);
+z.enum([
+  "domain_action",
+  "domain_trigger",
+  "system_crud",
+  "system_navigation",
+  "system_form",
+  "system_ui"
+]);
+z.enum([
+  "domain_core",
+  "domain_supporting",
+  "domain_reference",
+  "system_user",
+  "system_config",
+  "system_audit"
+]);
+var DomainVocabularySchema = z.record(z.string(), z.string()).optional();
+var UserPersonaSchema = z.object({
+  name: z.string().min(1),
+  role: z.string().optional(),
+  device: z.enum(["mobile", "tablet", "desktop"]).optional()
+});
+var DomainContextSchema = z.object({
+  request: z.string().min(1, "Original request is required"),
+  requestFragment: z.string().optional(),
+  category: AgentDomainCategorySchema,
+  subDomain: z.string().optional(),
+  personas: z.array(UserPersonaSchema).optional(),
+  vocabulary: DomainVocabularySchema.optional()
+});
+var UXHintsSchema = z.object({
+  flowPattern: z.string().optional(),
+  listPattern: z.string().optional(),
+  formPattern: z.string().optional(),
+  detailPattern: z.string().optional(),
+  relatedLinks: z.array(z.lazy(() => RelatedLinkSchema)).optional()
+});
+var RelatedLinkSchema = z.object({
+  relation: z.string().min(1),
+  label: z.string().min(1),
+  targetView: z.enum(["list", "detail"]).optional()
+});
+var SuggestedGuardSchema = z.object({
+  id: z.string().min(1),
+  description: z.string().min(1),
+  appliesTo: z.array(z.string().min(1))
+});
+var DesignPreferencesSchema = z.object({
+  style: z.enum(["minimal", "modern", "playful", "data-driven", "immersive"]).optional(),
+  primaryColor: z.string().regex(/^#[0-9A-Fa-f]{6}$/, "Must be valid hex color").optional(),
+  device: z.enum(["mobile", "tablet", "desktop", "all"]).optional(),
+  darkMode: z.boolean().optional(),
+  uxHints: UXHintsSchema.optional()
+});
+var ThemeTokensSchema = z.object({
+  colors: z.record(z.string(), z.string()).optional(),
+  radii: z.record(z.string(), z.string()).optional(),
+  spacing: z.record(z.string(), z.string()).optional(),
+  typography: z.record(z.string(), z.string()).optional(),
+  shadows: z.record(z.string(), z.string()).optional()
+});
+var ThemeVariantSchema = z.object({
+  colors: z.record(z.string(), z.string()).optional(),
+  radii: z.record(z.string(), z.string()).optional(),
+  spacing: z.record(z.string(), z.string()).optional(),
+  typography: z.record(z.string(), z.string()).optional(),
+  shadows: z.record(z.string(), z.string()).optional()
+});
+var ThemeDefinitionSchema = z.object({
+  name: z.string().min(1, "Theme name is required"),
+  tokens: ThemeTokensSchema,
+  variants: z.record(z.string(), ThemeVariantSchema).optional()
+});
+var ThemeRefStringSchema = z.string().regex(
+  /^[A-Z][a-zA-Z0-9]*\.theme$/,
+  'Theme reference must be in format "Alias.theme" (e.g., "Ocean.theme")'
+);
+var ThemeRefSchema = z.union([
+  ThemeDefinitionSchema,
+  ThemeRefStringSchema
+]);
+z.record(z.string(), z.record(z.string(), z.string())).optional();
+var ALLOWED_CUSTOM_COMPONENTS = [
+  "div",
+  "span",
+  "button",
+  "a",
+  "p",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "header",
+  "footer",
+  "section",
+  "article",
+  "nav",
+  "main",
+  "aside",
+  "ul",
+  "ol",
+  "li",
+  "img",
+  "label",
+  "input",
+  "form"
+];
+var CustomPatternDefinitionSchema = z.object({
+  type: z.literal("custom"),
+  component: z.enum(ALLOWED_CUSTOM_COMPONENTS),
+  className: z.string(),
+  slots: z.array(z.string()).optional(),
+  props: z.array(z.string()).optional()
+});
+z.record(z.string(), CustomPatternDefinitionSchema).optional();
+var SERVICE_TYPES = ["rest", "socket", "mcp"];
+z.enum(SERVICE_TYPES);
+var RestAuthConfigSchema = z.object({
+  type: z.enum(["api-key", "bearer", "basic", "oauth2"]),
+  keyName: z.string().optional(),
+  location: z.enum(["query", "header"]).optional(),
+  secretEnv: z.string().optional()
+});
+var RestServiceDefSchema = z.object({
+  name: z.string().min(1, "Service name is required"),
+  type: z.literal("rest"),
+  description: z.string().optional(),
+  baseUrl: z.string().url("Base URL must be a valid URL"),
+  headers: z.record(z.string()).optional(),
+  auth: RestAuthConfigSchema.optional(),
+  timeout: z.number().positive().optional()
+});
+var SocketEventsSchema = z.object({
+  inbound: z.array(z.string()),
+  outbound: z.array(z.string())
+});
+var SocketServiceDefSchema = z.object({
+  name: z.string().min(1, "Service name is required"),
+  type: z.literal("socket"),
+  description: z.string().optional(),
+  url: z.string().url("WebSocket URL must be valid"),
+  events: SocketEventsSchema,
+  reconnect: z.object({
+    enabled: z.boolean(),
+    maxAttempts: z.number().positive().optional(),
+    delayMs: z.number().positive().optional()
+  }).optional()
+});
+var McpServiceDefSchema = z.object({
+  name: z.string().min(1, "Service name is required"),
+  type: z.literal("mcp"),
+  description: z.string().optional(),
+  serverPath: z.string().min(1, "Server path is required"),
+  capabilities: z.array(z.string()).min(1, "At least one capability is required"),
+  env: z.record(z.string()).optional()
+});
+var ServiceDefinitionSchema = z.discriminatedUnion("type", [
+  RestServiceDefSchema,
+  SocketServiceDefSchema,
+  McpServiceDefSchema
+]);
+var ServiceRefStringSchema = z.string().regex(
+  /^[A-Z][a-zA-Z0-9]*\.services\.[a-zA-Z][a-zA-Z0-9]*$/,
+  'Service reference must be in format "Alias.services.ServiceName" (e.g., "Weather.services.openweather")'
+);
+var ServiceRefSchema = z.union([
+  ServiceDefinitionSchema,
+  ServiceRefStringSchema
+]);
+
+// src/types/orbital.ts
+var UseDeclarationSchema = z.object({
+  from: z.string().min(1, "Import source is required"),
+  as: z.string().min(1, "Alias is required").regex(
+    /^[A-Z][a-zA-Z0-9]*$/,
+    'Alias must be PascalCase (e.g., "Health", "GameCore")'
+  )
+});
+function isEntityReference(entity) {
+  return typeof entity === "string";
+}
+function isEntityCall(entity) {
+  return typeof entity === "object" && entity !== null && "extends" in entity;
+}
+var EntityRefStringSchema = z.string().regex(
+  /^[A-Z][a-zA-Z0-9]*\.entity$/,
+  'Entity reference must be in format "Alias.entity" (e.g., "Goblin.entity")'
+);
+var EntityCallSchema = z.object({
+  extends: z.string().regex(
+    /^[A-Z][a-zA-Z0-9]*\.entity$/,
+    'EntityCall "extends" must be in format "Alias.entity"'
+  ),
+  name: z.string().optional(),
+  fields: z.array(EntityFieldSchema).optional(),
+  persistence: EntityPersistenceSchema.optional(),
+  collection: z.string().optional()
+});
+var EntityRefSchema = z.union([
+  EntitySchema,
+  EntityRefStringSchema,
+  EntityCallSchema
+]);
+var PageRefStringSchema = z.string().regex(
+  /^[A-Z][a-zA-Z0-9]*\.pages\.[A-Z][a-zA-Z0-9]*$/,
+  'Page reference must be in format "Alias.pages.PageName" (e.g., "User.pages.Profile")'
+);
+var PageRefObjectSchema = z.object({
+  ref: PageRefStringSchema,
+  path: z.string().startsWith("/").optional(),
+  linkedEntity: z.string().optional(),
+  traits: z.array(TraitRefSchema).optional()
+});
+var PageRefSchema = z.union([
+  PageSchema,
+  PageRefStringSchema,
+  PageRefObjectSchema
+]);
+z.string().regex(
+  /^([A-Z][a-zA-Z0-9]*\.traits\.)?[A-Z][a-zA-Z0-9]*$/,
+  'Trait reference must be "TraitName" or "Alias.traits.TraitName"'
+);
+function parseEntityRef(ref) {
+  const match = ref.match(/^([A-Z][a-zA-Z0-9]*)\.entity$/);
+  if (!match) return null;
+  return { alias: match[1] };
+}
+z.object({
+  event: z.string().min(1),
+  triggers: z.string().min(1),
+  guard: z.string().optional()
+});
+var EventSourceSchema = z.object({
+  trait: z.string().min(1),
+  transition: z.string().optional(),
+  tick: z.string().optional()
+});
+var ComputedEventContractSchema = z.object({
+  event: z.string().min(1),
+  originalEvent: z.string().min(1),
+  source: EventSourceSchema,
+  description: z.string().optional(),
+  payload: z.array(EventPayloadFieldSchema).optional()
+});
+var ComputedEventListenerSchema = z.object({
+  event: z.string().min(1),
+  source: EventSourceSchema,
+  triggers: z.string().min(1),
+  guard: ExpressionSchema.optional(),
+  payloadMapping: z.record(z.string()).optional()
+});
+z.object({
+  name: z.string().min(1, "Orbital name is required"),
+  description: z.string().optional(),
+  visual_prompt: z.string().optional(),
+  // Import system
+  uses: z.array(UseDeclarationSchema).optional(),
+  // Theme & Services
+  theme: ThemeRefSchema.optional(),
+  services: z.array(ServiceRefSchema).optional(),
+  // Components (inline or reference)
+  entity: EntityRefSchema,
+  traits: z.array(TraitRefSchema),
+  pages: z.array(PageRefSchema),
+  // Event interface (trait-centric model) - computed by resolver
+  emits: z.array(ComputedEventContractSchema).optional(),
+  listens: z.array(ComputedEventListenerSchema).optional(),
+  // Filter for exposed events (trait-centric model)
+  exposes: z.array(z.string()).optional(),
+  // Context fields - persisted throughout orbital lifecycle
+  domainContext: DomainContextSchema.optional(),
+  design: DesignPreferencesSchema.optional(),
+  suggestedGuards: z.array(SuggestedGuardSchema).optional()
+});
+
+// src/builders/layout-strategy.ts
+function hasSequentialChain(wiring) {
+  if (wiring.length < 2) {
+    return false;
+  }
+  const adjacency = /* @__PURE__ */ new Map();
+  const allTargets = /* @__PURE__ */ new Set();
+  for (const entry of wiring) {
+    let targets = adjacency.get(entry.from);
+    if (!targets) {
+      targets = /* @__PURE__ */ new Set();
+      adjacency.set(entry.from, targets);
+    }
+    targets.add(entry.to);
+    allTargets.add(entry.to);
+  }
+  const roots = [];
+  for (const from of adjacency.keys()) {
+    if (!allTargets.has(from)) {
+      roots.push(from);
+    }
+  }
+  const starts = roots.length > 0 ? roots : [...adjacency.keys()];
+  for (const start of starts) {
+    let current = start;
+    let length = 1;
+    const visited = /* @__PURE__ */ new Set([current]);
+    while (true) {
+      const nexts = adjacency.get(current);
+      if (!nexts || nexts.size === 0) break;
+      let advanced = false;
+      for (const next of nexts) {
+        if (!visited.has(next)) {
+          visited.add(next);
+          current = next;
+          length++;
+          advanced = true;
+          break;
+        }
+      }
+      if (!advanced) break;
+    }
+    if (length >= 3) {
+      return true;
+    }
+  }
+  return false;
+}
+function detectLayoutStrategy(orbitals, eventWiring) {
+  if (eventWiring && eventWiring.length > 0 && hasSequentialChain(eventWiring)) {
+    return "wizard-flow";
+  }
+  const count = orbitals.length;
+  if (count <= 1) {
+    return "single";
+  }
+  if (count <= 4) {
+    return "tabs";
+  }
+  return "sidebar";
+}
 
 // src/builders/event-wiring.ts
 function findInlineTrait(orbitals, name) {
@@ -420,6 +936,16 @@ function ensureIdField(fields) {
 function plural(name) {
   return name + "s";
 }
+function resolveEntityNameForBuilder(ref) {
+  if (isEntityReference(ref)) {
+    return parseEntityRef(ref)?.alias ?? ref;
+  }
+  if (isEntityCall(ref)) {
+    if (ref.name) return ref.name;
+    return parseEntityRef(ref.extends)?.alias ?? ref.extends;
+  }
+  return ref.name;
+}
 function makeEntity(opts) {
   const fields = ensureIdField(opts.fields);
   const persistence = opts.persistence ?? "runtime";
@@ -552,7 +1078,7 @@ function pipe(orbitals, events, appName) {
     }
   }
   const pages = cloned.map((o, i) => {
-    const entityName = typeof o.entity === "string" ? o.entity : o.entity.name;
+    const entityName = resolveEntityNameForBuilder(o.entity);
     const traitNames = o.traits.map((t) => t.name);
     return {
       name: `${entityName}Page`,