@almadar/core 2.4.0 → 2.5.1

package/dist/builders.d.ts

@@ -1,4 +1,5 @@
-import { T as TraitEventContract, E as EntityField, a as EntityPersistence, O as OrbitalDefinition, b as OrbitalSchema, c as Trait, d as Entity, P as Page } from './schema-BrFR8WMF.js';
+import { T as TraitEventContract, E as EntityField, a as EntityPersistence, O as OrbitalDefinition, b as OrbitalSchema, c as Trait, d as Entity, P as Page } from './schema-DmrHbrqM.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-ClEyviUI.js';
 import 'zod';
 import '@almadar/patterns';
 
@@ -30,6 +31,8 @@ interface MakeEntityOpts {
     fields: EntityField[];
     persistence?: EntityPersistence;
     collection?: string;
+    /** Pre-authored seed data instances */
+    instances?: Record<string, unknown>[];
 }
 /**
  * Build an Entity from options. Auto-adds id field, auto-derives collection.

package/dist/builders.js

@@ -1,3 +1,416 @@
+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";
+}
+var UI_SLOTS = [
+  // App slots
+  "main",
+  "sidebar",
+  "modal",
+  "drawer",
+  "overlay",
+  "center",
+  "toast",
+  "floating",
+  "system",
+  // For invisible system components (InputListener, CollisionDetector)
+  "content",
+  "screen",
+  // Game HUD slots
+  "hud",
+  "hud-top",
+  "hud-bottom",
+  "hud.health",
+  "hud.score",
+  "hud.inventory",
+  "hud.stamina",
+  // Game overlay slots
+  "overlay.inventory",
+  "overlay.dialogue",
+  "overlay.menu",
+  "overlay.pause"
+];
+z.enum(UI_SLOTS);
+var EffectSchema = z.array(z.unknown()).min(1).refine(
+  (arr) => typeof arr[0] === "string",
+  { message: "Effect must be an S-expression with a string operator as first element" }
+);
+var SExprAtomSchema = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null(),
+  z.record(z.unknown())
+  // Objects for payload data
+]);
+var SExprSchema = z.lazy(
+  () => z.union([
+    SExprAtomSchema,
+    z.array(z.lazy(() => SExprSchema)).min(1).refine(
+      (arr) => typeof arr[0] === "string",
+      { message: "S-expression array must have a string operator as first element" }
+    )
+  ])
+);
+var ExpressionSchema = SExprSchema;
+
+// src/types/state-machine.ts
+var StateSchema = z.object({
+  name: z.string().min(1, "State name is required"),
+  isInitial: z.boolean().optional(),
+  isTerminal: z.boolean().optional(),
+  isFinal: z.boolean().optional(),
+  description: z.string().optional(),
+  onEntry: z.array(z.string()).optional(),
+  onExit: z.array(z.string()).optional()
+});
+var PayloadFieldSchema = z.object({
+  name: z.string().min(1),
+  type: z.enum(["string", "number", "boolean", "object", "array"]),
+  required: z.boolean().optional()
+});
+var EventSchema = z.object({
+  key: z.string().min(1, "Event key is required"),
+  name: z.string().min(1, "Event name is required"),
+  description: z.string().optional(),
+  payloadSchema: z.array(PayloadFieldSchema).optional(),
+  classification: z.enum(["domain", "system"]).optional(),
+  semanticRole: z.string().optional()
+});
+var GuardSchema = z.object({
+  name: z.string().min(1, "Guard name is required"),
+  expression: ExpressionSchema,
+  description: z.string().optional()
+});
+var TransitionSchema = z.object({
+  from: z.string().min(1, "Transition source state is required"),
+  to: z.string().min(1, "Transition target state is required"),
+  event: z.string().min(1, "Transition event is required"),
+  guard: ExpressionSchema.nullish(),
+  effects: z.array(EffectSchema).optional(),
+  description: z.string().nullish()
+});
+var StateMachineSchema = z.object({
+  states: z.array(StateSchema).min(1, "At least one state is required"),
+  events: z.array(EventSchema),
+  transitions: z.array(TransitionSchema),
+  guards: z.array(GuardSchema).optional()
+});
+
+// src/types/trait.ts
+var TraitCategorySchema = z.enum([
+  "lifecycle",
+  "temporal",
+  "validation",
+  "notification",
+  "integration",
+  "interaction",
+  "game-core",
+  "game-character",
+  "game-ai",
+  "game-combat",
+  "game-items",
+  "game-cards",
+  "game-board",
+  "game-puzzle"
+]);
+var TraitEntityFieldSchema = z.object({
+  name: z.string().min(1),
+  type: z.enum([
+    "string",
+    "number",
+    "boolean",
+    "date",
+    "array",
+    "object",
+    "timestamp",
+    "datetime",
+    "enum"
+  ]),
+  required: z.boolean().optional(),
+  default: z.unknown().optional(),
+  values: z.array(z.string()).optional()
+});
+var TraitDataEntitySchema = z.object({
+  name: z.string().min(1),
+  collection: z.string().optional(),
+  fields: z.array(TraitEntityFieldSchema).min(1),
+  timestamps: z.boolean().optional(),
+  description: z.string().optional(),
+  runtime: z.boolean().optional(),
+  singleton: z.boolean().optional(),
+  pages: z.array(z.string()).optional()
+});
+var TraitTickSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().optional(),
+  priority: z.number().optional(),
+  interval: z.union([z.literal("frame"), z.number().positive()]),
+  appliesTo: z.array(z.string()).optional(),
+  pages: z.array(z.string()).optional(),
+  guard: ExpressionSchema.optional(),
+  effects: z.array(EffectSchema).min(1),
+  emits: z.array(z.string()).optional()
+});
+var EventScopeSchema = z.enum(["internal", "external"]);
+var EventPayloadFieldSchema = z.object({
+  name: z.string().min(1),
+  type: z.enum(["string", "number", "boolean", "object", "array", "entity"]),
+  required: z.boolean().optional(),
+  description: z.string().optional(),
+  entityType: z.string().optional()
+});
+var TraitEventContractSchema = z.object({
+  event: z.string().min(1).regex(
+    /^[A-Z][A-Z0-9_]*$/,
+    "Event name must be UPPER_SNAKE_CASE"
+  ),
+  description: z.string().optional(),
+  payload: z.array(EventPayloadFieldSchema).optional(),
+  scope: EventScopeSchema.optional()
+});
+var TraitEventListenerSchema = z.object({
+  event: z.string().min(1),
+  triggers: z.string().min(1),
+  guard: ExpressionSchema.optional(),
+  scope: EventScopeSchema.optional(),
+  payloadMapping: z.record(z.string()).optional()
+});
+var RequiredFieldSchema = z.object({
+  name: z.string().min(1),
+  type: z.enum(["string", "number", "boolean", "date", "array", "object", "timestamp", "datetime", "enum"]),
+  description: z.string().optional()
+});
+z.object({
+  ref: z.string().min(1),
+  linkedEntity: z.string().optional(),
+  config: z.record(z.record(z.unknown())).optional(),
+  appliesTo: z.array(z.string()).optional()
+});
+var TraitSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().optional(),
+  description_visual_prompt: z.string().optional(),
+  category: TraitCategorySchema.optional(),
+  linkedEntity: z.string().optional(),
+  requiredFields: z.array(RequiredFieldSchema).optional(),
+  dataEntities: z.array(TraitDataEntitySchema).optional(),
+  stateMachine: StateMachineSchema.optional(),
+  initialEffects: z.array(EffectSchema).optional(),
+  ticks: z.array(TraitTickSchema).optional(),
+  emits: z.array(TraitEventContractSchema).optional(),
+  listens: z.array(TraitEventListenerSchema).optional(),
+  ui: z.record(z.unknown()).optional()
+});
+z.union([
+  z.string().min(1),
+  z.object({
+    ref: z.string().min(1),
+    config: z.record(z.unknown()).optional(),
+    linkedEntity: z.string().optional()
+  }),
+  TraitSchema
+  // Allow inline trait definitions
+]);
+function isInlineTrait(traitRef) {
+  return typeof traitRef === "object" && "name" in traitRef && !("ref" in traitRef);
+}
+
+// src/builders/event-wiring.ts
+function findInlineTrait(orbitals, name) {
+  for (const orbital of orbitals) {
+    for (const traitRef of orbital.traits) {
+      if (isInlineTrait(traitRef) && traitRef.name === name) {
+        return traitRef;
+      }
+    }
+  }
+  return null;
+}
+function hasEmit(emits, event) {
+  return emits.some((e) => e.event === event);
+}
+function hasListen(listens, event, triggers) {
+  return listens.some((l) => l.event === event && l.triggers === triggers);
+}
+function applyEventWiring(orbitals, wiring) {
+  const cloned = JSON.parse(
+    JSON.stringify(orbitals)
+  );
+  for (const entry of wiring) {
+    const sourceTrait = findInlineTrait(cloned, entry.from);
+    if (sourceTrait) {
+      if (!sourceTrait.emits) {
+        sourceTrait.emits = [];
+      }
+      if (!hasEmit(sourceTrait.emits, entry.event)) {
+        sourceTrait.emits.push({
+          event: entry.event,
+          scope: "external"
+        });
+      }
+    }
+    const targetTrait = findInlineTrait(cloned, entry.to);
+    if (targetTrait) {
+      if (!targetTrait.listens) {
+        targetTrait.listens = [];
+      }
+      if (!hasListen(targetTrait.listens, entry.event, entry.triggers)) {
+        targetTrait.listens.push({
+          event: entry.event,
+          triggers: entry.triggers,
+          scope: "external"
+        });
+      }
+    }
+  }
+  return cloned;
+}
+
+// src/builders/compose-behaviors.ts
+function toKebabCase(name) {
+  return name.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
+}
+function generatePages(orbitals, strategy) {
+  switch (strategy) {
+    case "single": {
+      const orbital = orbitals[0];
+      const name = orbital?.name ?? "Main";
+      return [
+        {
+          name: `${name}Page`,
+          path: "/",
+          isInitial: true,
+          primaryEntity: getEntityName(orbital)
+        }
+      ];
+    }
+    case "dashboard": {
+      return [
+        {
+          name: "DashboardPage",
+          path: "/",
+          viewType: "dashboard",
+          isInitial: true
+        }
+      ];
+    }
+    case "sidebar":
+    case "tabs":
+    case "wizard-flow": {
+      return orbitals.map((orbital, index) => ({
+        name: `${orbital.name}Page`,
+        path: index === 0 ? "/" : `/${toKebabCase(orbital.name)}`,
+        isInitial: index === 0,
+        primaryEntity: getEntityName(orbital)
+      }));
+    }
+  }
+}
+function getEntityName(orbital) {
+  if (!orbital) return void 0;
+  const entity = orbital.entity;
+  if (typeof entity === "string") {
+    return entity.replace(".entity", "");
+  }
+  return entity.name;
+}
+function composeBehaviors(input) {
+  const {
+    appName,
+    orbitals: rawOrbitals,
+    layoutStrategy: strategyInput,
+    eventWiring
+  } = input;
+  const wiredOrbitals = eventWiring && eventWiring.length > 0 ? applyEventWiring(rawOrbitals, eventWiring) : rawOrbitals;
+  const strategy = !strategyInput || strategyInput === "auto" ? detectLayoutStrategy(wiredOrbitals, eventWiring) : strategyInput;
+  const pages = generatePages(wiredOrbitals, strategy);
+  const orbitalsWithPages = wiredOrbitals.map((orbital, index) => {
+    if (orbital.pages && orbital.pages.length > 0) {
+      return orbital;
+    }
+    const page = strategy === "dashboard" || strategy === "single" ? pages[0] : pages[index];
+    return {
+      ...orbital,
+      pages: page ? [page] : []
+    };
+  });
+  const schema = {
+    name: appName,
+    version: "1.0.0",
+    orbitals: orbitalsWithPages
+  };
+  return {
+    schema,
+    layout: {
+      strategy,
+      pageCount: pages.length
+    },
+    wiring: {
+      connections: eventWiring?.length ?? 0
+    }
+  };
+}
+
 // src/builders.ts
 function ensureIdField(fields) {
   if (fields.some((f) => f.name === "id")) return fields;
@@ -13,7 +426,8 @@ function makeEntity(opts) {
     name: opts.name,
     persistence,
     ...persistence === "persistent" ? { collection: opts.collection ?? plural(opts.name).toLowerCase() } : {},
-    fields
+    fields,
+    ...opts.instances && opts.instances.length > 0 ? { instances: opts.instances } : {}
   };
 }
 function makePage(opts) {
@@ -156,6 +570,6 @@ function pipe(orbitals, events, appName) {
   };
 }
 
-export { compose, connect, ensureIdField, extractTrait, makeEntity, makeOrbital, makePage, mergeOrbitals, pipe, plural, wire };
+export { applyEventWiring, compose, composeBehaviors, connect, detectLayoutStrategy, ensureIdField, extractTrait, makeEntity, makeOrbital, makePage, mergeOrbitals, pipe, plural, wire };
 //# sourceMappingURL=builders.js.map
 //# sourceMappingURL=builders.js.map