@almadar/ui 3.1.3 → 3.2.0

package/dist/avl/index.cjs

@@ -11916,12 +11916,19 @@ function getState() {
         checks: /* @__PURE__ */ new Map(),
         transitions: [],
         bridgeHealth: null,
-        listeners: /* @__PURE__ */ new Set()
+        listeners: /* @__PURE__ */ new Set(),
+        traitSnapshots: /* @__PURE__ */ new Map()
       };
     }
     return w.__verificationRegistryState;
   }
-  return { checks: /* @__PURE__ */ new Map(), transitions: [], bridgeHealth: null, listeners: /* @__PURE__ */ new Set() };
+  return {
+    checks: /* @__PURE__ */ new Map(),
+    transitions: [],
+    bridgeHealth: null,
+    listeners: /* @__PURE__ */ new Set(),
+    traitSnapshots: /* @__PURE__ */ new Map()
+  };
 }
 function notifyListeners() {
   getState().listeners.forEach((l) => l());
@@ -12028,9 +12035,21 @@ function getSnapshot() {
     checks: getAllChecks(),
     transitions: getTransitions2(),
     bridge: getBridgeHealth(),
-    summary: getSummary()
+    summary: getSummary(),
+    traits: getTraitSnapshots()
   };
 }
+function getTraitSnapshots() {
+  const snapshots = [];
+  for (const [traitName, getter] of getState().traitSnapshots.entries()) {
+    try {
+      snapshots.push(getter());
+    } catch (err) {
+      log2.error("traitSnapshot getter failed", { trait: traitName, err: String(err) });
+    }
+  }
+  return snapshots;
+}
 function subscribeToVerification(listener) {
   getState().listeners.add(listener);
   return () => getState().listeners.delete(listener);
@@ -12044,8 +12063,11 @@ function exposeOnWindow() {
       getTransitions: getTransitions2,
       getBridge: getBridgeHealth,
       getSummary,
-      waitForTransition
+      waitForTransition,
+      getTraitSnapshots
     };
+  } else if (!window.__orbitalVerification.getTraitSnapshots) {
+    window.__orbitalVerification.getTraitSnapshots = getTraitSnapshots;
   }
 }
 function waitForTransition(event, timeoutMs = 1e4) {

package/dist/avl/index.js

@@ -11870,12 +11870,19 @@ function getState() {
         checks: /* @__PURE__ */ new Map(),
         transitions: [],
         bridgeHealth: null,
-        listeners: /* @__PURE__ */ new Set()
+        listeners: /* @__PURE__ */ new Set(),
+        traitSnapshots: /* @__PURE__ */ new Map()
       };
     }
     return w.__verificationRegistryState;
   }
-  return { checks: /* @__PURE__ */ new Map(), transitions: [], bridgeHealth: null, listeners: /* @__PURE__ */ new Set() };
+  return {
+    checks: /* @__PURE__ */ new Map(),
+    transitions: [],
+    bridgeHealth: null,
+    listeners: /* @__PURE__ */ new Set(),
+    traitSnapshots: /* @__PURE__ */ new Map()
+  };
 }
 function notifyListeners() {
   getState().listeners.forEach((l) => l());
@@ -11982,9 +11989,21 @@ function getSnapshot() {
     checks: getAllChecks(),
     transitions: getTransitions2(),
     bridge: getBridgeHealth(),
-    summary: getSummary()
+    summary: getSummary(),
+    traits: getTraitSnapshots()
   };
 }
+function getTraitSnapshots() {
+  const snapshots = [];
+  for (const [traitName, getter] of getState().traitSnapshots.entries()) {
+    try {
+      snapshots.push(getter());
+    } catch (err) {
+      log2.error("traitSnapshot getter failed", { trait: traitName, err: String(err) });
+    }
+  }
+  return snapshots;
+}
 function subscribeToVerification(listener) {
   getState().listeners.add(listener);
   return () => getState().listeners.delete(listener);
@@ -11998,8 +12017,11 @@ function exposeOnWindow() {
       getTransitions: getTransitions2,
       getBridge: getBridgeHealth,
       getSummary,
-      waitForTransition
+      waitForTransition,
+      getTraitSnapshots
     };
+  } else if (!window.__orbitalVerification.getTraitSnapshots) {
+    window.__orbitalVerification.getTraitSnapshots = getTraitSnapshots;
   }
 }
 function waitForTransition(event, timeoutMs = 1e4) {

package/dist/components/index.cjs

@@ -7443,12 +7443,19 @@ function getState() {
         checks: /* @__PURE__ */ new Map(),
         transitions: [],
         bridgeHealth: null,
-        listeners: /* @__PURE__ */ new Set()
+        listeners: /* @__PURE__ */ new Set(),
+        traitSnapshots: /* @__PURE__ */ new Map()
       };
     }
     return w.__verificationRegistryState;
   }
-  return { checks: /* @__PURE__ */ new Map(), transitions: [], bridgeHealth: null, listeners: /* @__PURE__ */ new Set() };
+  return {
+    checks: /* @__PURE__ */ new Map(),
+    transitions: [],
+    bridgeHealth: null,
+    listeners: /* @__PURE__ */ new Set(),
+    traitSnapshots: /* @__PURE__ */ new Map()
+  };
 }
 function getAllChecks() {
   return Array.from(getState().checks.values());
@@ -7475,9 +7482,21 @@ function getSnapshot() {
     checks: getAllChecks(),
     transitions: getTransitions(),
     bridge: getBridgeHealth(),
-    summary: getSummary()
+    summary: getSummary(),
+    traits: getTraitSnapshots()
   };
 }
+function getTraitSnapshots() {
+  const snapshots = [];
+  for (const [traitName, getter] of getState().traitSnapshots.entries()) {
+    try {
+      snapshots.push(getter());
+    } catch (err) {
+      log2.error("traitSnapshot getter failed", { trait: traitName, err: String(err) });
+    }
+  }
+  return snapshots;
+}
 function subscribeToVerification(listener) {
   getState().listeners.add(listener);
   return () => getState().listeners.delete(listener);
@@ -7491,8 +7510,11 @@ function exposeOnWindow() {
       getTransitions,
       getBridge: getBridgeHealth,
       getSummary,
-      waitForTransition
+      waitForTransition,
+      getTraitSnapshots
     };
+  } else if (!window.__orbitalVerification.getTraitSnapshots) {
+    window.__orbitalVerification.getTraitSnapshots = getTraitSnapshots;
   }
 }
 function waitForTransition(event, timeoutMs = 1e4) {
@@ -7533,10 +7555,11 @@ function updateAssetStatus(url, status) {
     window.__orbitalVerification.assetStatus[url] = status;
   }
 }
+var log2;
 var init_verificationRegistry = __esm({
   "lib/verificationRegistry.ts"() {
     init_logger();
-    createLogger("almadar:bridge");
+    log2 = createLogger("almadar:bridge");
     exposeOnWindow();
   }
 });

package/dist/components/index.js

@@ -7398,12 +7398,19 @@ function getState() {
         checks: /* @__PURE__ */ new Map(),
         transitions: [],
         bridgeHealth: null,
-        listeners: /* @__PURE__ */ new Set()
+        listeners: /* @__PURE__ */ new Set(),
+        traitSnapshots: /* @__PURE__ */ new Map()
       };
     }
     return w.__verificationRegistryState;
   }
-  return { checks: /* @__PURE__ */ new Map(), transitions: [], bridgeHealth: null, listeners: /* @__PURE__ */ new Set() };
+  return {
+    checks: /* @__PURE__ */ new Map(),
+    transitions: [],
+    bridgeHealth: null,
+    listeners: /* @__PURE__ */ new Set(),
+    traitSnapshots: /* @__PURE__ */ new Map()
+  };
 }
 function getAllChecks() {
   return Array.from(getState().checks.values());
@@ -7430,9 +7437,21 @@ function getSnapshot() {
     checks: getAllChecks(),
     transitions: getTransitions(),
     bridge: getBridgeHealth(),
-    summary: getSummary()
+    summary: getSummary(),
+    traits: getTraitSnapshots()
   };
 }
+function getTraitSnapshots() {
+  const snapshots = [];
+  for (const [traitName, getter] of getState().traitSnapshots.entries()) {
+    try {
+      snapshots.push(getter());
+    } catch (err) {
+      log2.error("traitSnapshot getter failed", { trait: traitName, err: String(err) });
+    }
+  }
+  return snapshots;
+}
 function subscribeToVerification(listener) {
   getState().listeners.add(listener);
   return () => getState().listeners.delete(listener);
@@ -7446,8 +7465,11 @@ function exposeOnWindow() {
       getTransitions,
       getBridge: getBridgeHealth,
       getSummary,
-      waitForTransition
+      waitForTransition,
+      getTraitSnapshots
     };
+  } else if (!window.__orbitalVerification.getTraitSnapshots) {
+    window.__orbitalVerification.getTraitSnapshots = getTraitSnapshots;
   }
 }
 function waitForTransition(event, timeoutMs = 1e4) {
@@ -7488,10 +7510,11 @@ function updateAssetStatus(url, status) {
     window.__orbitalVerification.assetStatus[url] = status;
   }
 }
+var log2;
 var init_verificationRegistry = __esm({
   "lib/verificationRegistry.ts"() {
     init_logger();
-    createLogger("almadar:bridge");
+    log2 = createLogger("almadar:bridge");
     exposeOnWindow();
   }
 });

package/dist/hooks/useUIEvents.d.ts

@@ -1,4 +1,5 @@
 import { useEventBus } from "./useEventBus";
+import type { EventPayload } from "@almadar/core";
 /**
  * Hook to bridge UI events to state machine dispatch
  *
@@ -6,7 +7,7 @@ import { useEventBus } from "./useEventBus";
  * @param validEvents - Optional array of valid event names (filters which events to handle)
  * @param eventBusInstance - Optional event bus instance (for testing, uses hook if not provided)
  */
-export declare function useUIEvents<E extends string>(dispatch: (event: E, payload?: unknown) => void, validEvents?: readonly E[], eventBusInstance?: ReturnType<typeof useEventBus>): void;
+export declare function useUIEvents<E extends string>(dispatch: (event: E, payload?: EventPayload) => void, validEvents?: readonly E[], eventBusInstance?: ReturnType<typeof useEventBus>): void;
 /**
  * Hook for selected entity tracking
  * Many list UIs need to track which item is selected.

package/dist/lib/index.cjs

@@ -493,12 +493,19 @@ function getState() {
         checks: /* @__PURE__ */ new Map(),
         transitions: [],
         bridgeHealth: null,
-        listeners: /* @__PURE__ */ new Set()
+        listeners: /* @__PURE__ */ new Set(),
+        traitSnapshots: /* @__PURE__ */ new Map()
       };
     }
     return w.__verificationRegistryState;
   }
-  return { checks: /* @__PURE__ */ new Map(), transitions: [], bridgeHealth: null, listeners: /* @__PURE__ */ new Set() };
+  return {
+    checks: /* @__PURE__ */ new Map(),
+    transitions: [],
+    bridgeHealth: null,
+    listeners: /* @__PURE__ */ new Set(),
+    traitSnapshots: /* @__PURE__ */ new Map()
+  };
 }
 function notifyListeners5() {
   getState().listeners.forEach((l) => l());
@@ -634,9 +641,21 @@ function getSnapshot() {
     checks: getAllChecks(),
     transitions: getTransitions(),
     bridge: getBridgeHealth(),
-    summary: getSummary()
+    summary: getSummary(),
+    traits: getTraitSnapshots()
   };
 }
+function getTraitSnapshots() {
+  const snapshots = [];
+  for (const [traitName, getter] of getState().traitSnapshots.entries()) {
+    try {
+      snapshots.push(getter());
+    } catch (err) {
+      log.error("traitSnapshot getter failed", { trait: traitName, err: String(err) });
+    }
+  }
+  return snapshots;
+}
 function subscribeToVerification(listener) {
   getState().listeners.add(listener);
   return () => getState().listeners.delete(listener);
@@ -650,8 +669,11 @@ function exposeOnWindow() {
       getTransitions,
       getBridge: getBridgeHealth,
       getSummary,
-      waitForTransition
+      waitForTransition,
+      getTraitSnapshots
     };
+  } else if (!window.__orbitalVerification.getTraitSnapshots) {
+    window.__orbitalVerification.getTraitSnapshots = getTraitSnapshots;
   }
 }
 function waitForTransition(event, timeoutMs = 1e4) {
@@ -710,6 +732,20 @@ function bindTraitStateGetter(getter) {
     window.__orbitalVerification.getTraitState = getter;
   }
 }
+function registerTraitSnapshot(traitName, getter) {
+  if (typeof window === "undefined") return () => {
+  };
+  getState().traitSnapshots.set(traitName, getter);
+  exposeOnWindow();
+  notifyListeners5();
+  return () => {
+    const s = getState();
+    if (s.traitSnapshots.get(traitName) === getter) {
+      s.traitSnapshots.delete(traitName);
+      notifyListeners5();
+    }
+  };
+}
 function bindCanvasCapture(captureFn) {
   if (typeof window === "undefined") return;
   exposeOnWindow();
@@ -1558,6 +1594,7 @@ exports.getSnapshot = getSnapshot;
 exports.getSummary = getSummary;
 exports.getTick = getTick;
 exports.getTrait = getTrait;
+exports.getTraitSnapshots = getTraitSnapshots;
 exports.getTransitions = getTransitions;
 exports.getTransitionsForTrait = getTransitionsForTrait;
 exports.initDebugShortcut = initDebugShortcut;
@@ -1578,6 +1615,7 @@ exports.recordTransition = recordTransition;
 exports.registerCheck = registerCheck;
 exports.registerTick = registerTick;
 exports.registerTrait = registerTrait;
+exports.registerTraitSnapshot = registerTraitSnapshot;
 exports.renderStateMachineToDomData = renderStateMachineToDomData;
 exports.renderStateMachineToSvg = renderStateMachineToSvg;
 exports.setDebugEnabled = setDebugEnabled;

package/dist/lib/index.js

@@ -491,12 +491,19 @@ function getState() {
         checks: /* @__PURE__ */ new Map(),
         transitions: [],
         bridgeHealth: null,
-        listeners: /* @__PURE__ */ new Set()
+        listeners: /* @__PURE__ */ new Set(),
+        traitSnapshots: /* @__PURE__ */ new Map()
       };
     }
     return w.__verificationRegistryState;
   }
-  return { checks: /* @__PURE__ */ new Map(), transitions: [], bridgeHealth: null, listeners: /* @__PURE__ */ new Set() };
+  return {
+    checks: /* @__PURE__ */ new Map(),
+    transitions: [],
+    bridgeHealth: null,
+    listeners: /* @__PURE__ */ new Set(),
+    traitSnapshots: /* @__PURE__ */ new Map()
+  };
 }
 function notifyListeners5() {
   getState().listeners.forEach((l) => l());
@@ -632,9 +639,21 @@ function getSnapshot() {
     checks: getAllChecks(),
     transitions: getTransitions(),
     bridge: getBridgeHealth(),
-    summary: getSummary()
+    summary: getSummary(),
+    traits: getTraitSnapshots()
   };
 }
+function getTraitSnapshots() {
+  const snapshots = [];
+  for (const [traitName, getter] of getState().traitSnapshots.entries()) {
+    try {
+      snapshots.push(getter());
+    } catch (err) {
+      log.error("traitSnapshot getter failed", { trait: traitName, err: String(err) });
+    }
+  }
+  return snapshots;
+}
 function subscribeToVerification(listener) {
   getState().listeners.add(listener);
   return () => getState().listeners.delete(listener);
@@ -648,8 +667,11 @@ function exposeOnWindow() {
       getTransitions,
       getBridge: getBridgeHealth,
       getSummary,
-      waitForTransition
+      waitForTransition,
+      getTraitSnapshots
     };
+  } else if (!window.__orbitalVerification.getTraitSnapshots) {
+    window.__orbitalVerification.getTraitSnapshots = getTraitSnapshots;
   }
 }
 function waitForTransition(event, timeoutMs = 1e4) {
@@ -708,6 +730,20 @@ function bindTraitStateGetter(getter) {
     window.__orbitalVerification.getTraitState = getter;
   }
 }
+function registerTraitSnapshot(traitName, getter) {
+  if (typeof window === "undefined") return () => {
+  };
+  getState().traitSnapshots.set(traitName, getter);
+  exposeOnWindow();
+  notifyListeners5();
+  return () => {
+    const s = getState();
+    if (s.traitSnapshots.get(traitName) === getter) {
+      s.traitSnapshots.delete(traitName);
+      notifyListeners5();
+    }
+  };
+}
 function bindCanvasCapture(captureFn) {
   if (typeof window === "undefined") return;
   exposeOnWindow();
@@ -1505,4 +1541,4 @@ function parseContentSegments(content) {
   return segments;
 }
 
-export { ApiError, DEFAULT_CONFIG, apiClient, bindCanvasCapture, bindEventBus, bindTraitStateGetter, clearDebugEvents, clearEntityProvider, clearGuardHistory, clearTicks, clearTraits, clearVerification, cn, createLogger, debug, debugCollision, debugError, debugGameState, debugGroup, debugGroupEnd, debugInput, debugPhysics, debugTable, debugTime, debugTimeEnd, debugWarn, extractOutputsFromTransitions, extractStateMachine, formatGuard, formatNestedFieldLabel, generateCorrelationId, getAllChecks, getAllTicks, getAllTraits, getBridgeHealth, getDebugEvents, getEffectSummary, getEntitiesByType, getEntityById, getEntitySnapshot, getEventsBySource, getEventsByType, getGuardEvaluationsForTrait, getGuardHistory, getNestedValue, getRecentEvents, getRecentGuardEvaluations, getSnapshot, getSummary, getTick, getTrait, getTransitions, getTransitionsForTrait, initDebugShortcut, isDebugEnabled, logDebugEvent, logEffectExecuted, logError, logEventFired, logInfo, logStateChange, logWarning, onDebugToggle, parseContentSegments, parseMarkdownWithCodeBlocks, recordGuardEvaluation, recordServerResponse, recordTransition, registerCheck, registerTick, registerTrait, renderStateMachineToDomData, renderStateMachineToSvg, setDebugEnabled, setEntityProvider, setTickActive, subscribeToDebugEvents, subscribeToGuardChanges, subscribeToTickChanges, subscribeToTraitChanges, subscribeToVerification, toggleDebug, unregisterTick, unregisterTrait, updateAssetStatus, updateBridgeHealth, updateCheck, updateGuardResult, updateTickExecution, updateTraitState, waitForTransition };
+export { ApiError, DEFAULT_CONFIG, apiClient, bindCanvasCapture, bindEventBus, bindTraitStateGetter, clearDebugEvents, clearEntityProvider, clearGuardHistory, clearTicks, clearTraits, clearVerification, cn, createLogger, debug, debugCollision, debugError, debugGameState, debugGroup, debugGroupEnd, debugInput, debugPhysics, debugTable, debugTime, debugTimeEnd, debugWarn, extractOutputsFromTransitions, extractStateMachine, formatGuard, formatNestedFieldLabel, generateCorrelationId, getAllChecks, getAllTicks, getAllTraits, getBridgeHealth, getDebugEvents, getEffectSummary, getEntitiesByType, getEntityById, getEntitySnapshot, getEventsBySource, getEventsByType, getGuardEvaluationsForTrait, getGuardHistory, getNestedValue, getRecentEvents, getRecentGuardEvaluations, getSnapshot, getSummary, getTick, getTrait, getTraitSnapshots, getTransitions, getTransitionsForTrait, initDebugShortcut, isDebugEnabled, logDebugEvent, logEffectExecuted, logError, logEventFired, logInfo, logStateChange, logWarning, onDebugToggle, parseContentSegments, parseMarkdownWithCodeBlocks, recordGuardEvaluation, recordServerResponse, recordTransition, registerCheck, registerTick, registerTrait, registerTraitSnapshot, renderStateMachineToDomData, renderStateMachineToSvg, setDebugEnabled, setEntityProvider, setTickActive, subscribeToDebugEvents, subscribeToGuardChanges, subscribeToTickChanges, subscribeToTraitChanges, subscribeToVerification, toggleDebug, unregisterTick, unregisterTrait, updateAssetStatus, updateBridgeHealth, updateCheck, updateGuardResult, updateTickExecution, updateTraitState, waitForTransition };

package/dist/lib/verificationRegistry.d.ts

@@ -9,7 +9,7 @@
  *
  * @packageDocumentation
  */
-import type { BusEvent, EventPayload } from '@almadar/core';
+import type { BusEvent, BusEventSource, EntityRow, EventPayload } from '@almadar/core';
 export type CheckStatus = "pass" | "fail" | "pending" | "warn";
 export interface VerificationCheck {
     id: string;
@@ -63,13 +63,67 @@ export interface VerificationSummary {
     warnings: number;
     pending: number;
 }
+/**
+ * Per-trait state snapshot exposed to the verifier so it can assert that
+ * reducer data (populated by fetch/persist transitions) and the last
+ * dispatched payload land in the DOM correctly (VG4/VG6/VG11a/b/c).
+ *
+ * Mirrors what `useTraitStateMachine` / generated trait logic hooks keep
+ * internally, without the verifier having to parse rendered text.
+ */
+export interface TraitStateSnapshot {
+    /** Trait name as declared in the schema. */
+    traitName: string;
+    /** Current state machine state. */
+    currentState: string;
+    /** Declared state names for this trait (non-empty for healthy trait refs). */
+    states: string[];
+    /** Declared event keys for this trait (non-empty for healthy trait refs). */
+    events: string[];
+    /**
+     * Entity data keyed by entity name. Same shape the trait reducer holds
+     * in `state.data`. Snapshot-on-read; mutating the returned arrays does
+     * not affect the live reducer.
+     */
+    data: Record<string, EntityRow[]>;
+    /** Payload of the last event the state machine processed, if any. */
+    lastPayload?: EventPayload;
+    /**
+     * Last event the walker (or a UI click) dispatched into this trait.
+     * Used by VG11a to resolve `@payload.X` expected values.
+     */
+    lastEventDispatched?: {
+        event: string;
+        payload?: EventPayload;
+        source?: BusEventSource;
+        timestamp: number;
+    };
+    /**
+     * Bus events received from the server's `emittedEvents` cascade since the
+     * last user dispatch. VG4 compares the length against the number of
+     * `emit: { success/failure: ... }` entries on the triggering transition.
+     */
+    cascadeReceived: Array<{
+        event: string;
+        payload?: EventPayload;
+        timestamp: number;
+    }>;
+}
 export interface VerificationSnapshot {
     checks: VerificationCheck[];
     transitions: TransitionTrace[];
     bridge: BridgeHealth | null;
     summary: VerificationSummary;
+    /** Per-trait reducer snapshot (populated once `bindTraitSnapshotGetter` runs). */
+    traits: TraitStateSnapshot[];
 }
 type ChangeListener = () => void;
+/**
+ * Per-trait snapshot getter. Each generated trait logic hook (or
+ * `useTraitStateMachine` trait binding) registers one on mount so the
+ * verifier can read the live reducer state for that trait.
+ */
+export type TraitSnapshotGetter = () => TraitStateSnapshot;
 export declare function registerCheck(id: string, label: string, status?: CheckStatus, details?: string): void;
 export declare function updateCheck(id: string, status: CheckStatus, details?: string): void;
 export declare function getAllChecks(): VerificationCheck[];
@@ -86,6 +140,15 @@ export declare function updateBridgeHealth(health: BridgeHealth): void;
 export declare function getBridgeHealth(): BridgeHealth | null;
 export declare function getSummary(): VerificationSummary;
 export declare function getSnapshot(): VerificationSnapshot;
+/**
+ * Per-trait snapshot for the verifier.
+ *
+ * Iterates every registered trait getter and collects the live reducer
+ * state. Empty until at least one trait hook calls `registerTraitSnapshot`.
+ * A getter that throws is logged and skipped — one broken trait must not
+ * poison the rest of the snapshot.
+ */
+export declare function getTraitSnapshots(): TraitStateSnapshot[];
 export declare function subscribeToVerification(listener: ChangeListener): () => void;
 /** Asset load status for canvas verification */
 export type AssetLoadStatus = "loaded" | "failed" | "pending";
@@ -108,6 +171,8 @@ interface OrbitalVerificationAPI {
     sendEvent?: (event: string, payload?: Record<string, unknown>) => void;
     /** Get current trait state */
     getTraitState?: (traitName: string) => string | undefined;
+    /** Per-trait reducer snapshots (VG4/VG6/VG11a/b/c). */
+    getTraitSnapshots?: () => TraitStateSnapshot[];
     /** Capture a canvas frame as PNG data URL. Registered by game organisms. */
     captureFrame?: () => string | null;
     /** Asset load status map. Registered by game organisms. */
@@ -139,6 +204,17 @@ export declare function bindEventBus(eventBus: {
  * Bind a trait state getter so automation can query current states.
  */
 export declare function bindTraitStateGetter(getter: (traitName: string) => string | undefined): void;
+/**
+ * Register a per-trait snapshot provider. The generated trait logic hook
+ * (or `useTraitStateMachine`) calls this once on mount, passing a getter
+ * that reads the current reducer state via a ref. Returns an unregister
+ * function for cleanup on unmount.
+ *
+ * Calling this twice for the same `traitName` replaces the previous
+ * getter (e.g. page navigation remounts the trait; the new registration
+ * wins).
+ */
+export declare function registerTraitSnapshot(traitName: string, getter: TraitSnapshotGetter): () => void;
 /**
  * Register a canvas frame capture function.
  * Called by game organisms (IsometricCanvas, PlatformerCanvas, SimulationCanvas)

package/dist/providers/index.cjs

@@ -8901,12 +8901,19 @@ function getState() {
         checks: /* @__PURE__ */ new Map(),
         transitions: [],
         bridgeHealth: null,
-        listeners: /* @__PURE__ */ new Set()
+        listeners: /* @__PURE__ */ new Set(),
+        traitSnapshots: /* @__PURE__ */ new Map()
       };
     }
     return w.__verificationRegistryState;
   }
-  return { checks: /* @__PURE__ */ new Map(), transitions: [], bridgeHealth: null, listeners: /* @__PURE__ */ new Set() };
+  return {
+    checks: /* @__PURE__ */ new Map(),
+    transitions: [],
+    bridgeHealth: null,
+    listeners: /* @__PURE__ */ new Set(),
+    traitSnapshots: /* @__PURE__ */ new Map()
+  };
 }
 function notifyListeners() {
   getState().listeners.forEach((l) => l());
@@ -8983,9 +8990,21 @@ function getSnapshot() {
     checks: getAllChecks(),
     transitions: getTransitions(),
     bridge: getBridgeHealth(),
-    summary: getSummary()
+    summary: getSummary(),
+    traits: getTraitSnapshots()
   };
 }
+function getTraitSnapshots() {
+  const snapshots = [];
+  for (const [traitName, getter] of getState().traitSnapshots.entries()) {
+    try {
+      snapshots.push(getter());
+    } catch (err) {
+      log2.error("traitSnapshot getter failed", { trait: traitName, err: String(err) });
+    }
+  }
+  return snapshots;
+}
 function subscribeToVerification(listener) {
   getState().listeners.add(listener);
   return () => getState().listeners.delete(listener);
@@ -8999,8 +9018,11 @@ function exposeOnWindow() {
       getTransitions,
       getBridge: getBridgeHealth,
       getSummary,
-      waitForTransition
+      waitForTransition,
+      getTraitSnapshots
     };
+  } else if (!window.__orbitalVerification.getTraitSnapshots) {
+    window.__orbitalVerification.getTraitSnapshots = getTraitSnapshots;
   }
 }
 function waitForTransition(event, timeoutMs = 1e4) {

package/dist/providers/index.js

@@ -8856,12 +8856,19 @@ function getState() {
         checks: /* @__PURE__ */ new Map(),
         transitions: [],
         bridgeHealth: null,
-        listeners: /* @__PURE__ */ new Set()
+        listeners: /* @__PURE__ */ new Set(),
+        traitSnapshots: /* @__PURE__ */ new Map()
       };
     }
     return w.__verificationRegistryState;
   }
-  return { checks: /* @__PURE__ */ new Map(), transitions: [], bridgeHealth: null, listeners: /* @__PURE__ */ new Set() };
+  return {
+    checks: /* @__PURE__ */ new Map(),
+    transitions: [],
+    bridgeHealth: null,
+    listeners: /* @__PURE__ */ new Set(),
+    traitSnapshots: /* @__PURE__ */ new Map()
+  };
 }
 function notifyListeners() {
   getState().listeners.forEach((l) => l());
@@ -8938,9 +8945,21 @@ function getSnapshot() {
     checks: getAllChecks(),
     transitions: getTransitions(),
     bridge: getBridgeHealth(),
-    summary: getSummary()
+    summary: getSummary(),
+    traits: getTraitSnapshots()
   };
 }
+function getTraitSnapshots() {
+  const snapshots = [];
+  for (const [traitName, getter] of getState().traitSnapshots.entries()) {
+    try {
+      snapshots.push(getter());
+    } catch (err) {
+      log2.error("traitSnapshot getter failed", { trait: traitName, err: String(err) });
+    }
+  }
+  return snapshots;
+}
 function subscribeToVerification(listener) {
   getState().listeners.add(listener);
   return () => getState().listeners.delete(listener);
@@ -8954,8 +8973,11 @@ function exposeOnWindow() {
       getTransitions,
       getBridge: getBridgeHealth,
       getSummary,
-      waitForTransition
+      waitForTransition,
+      getTraitSnapshots
     };
+  } else if (!window.__orbitalVerification.getTraitSnapshots) {
+    window.__orbitalVerification.getTraitSnapshots = getTraitSnapshots;
   }
 }
 function waitForTransition(event, timeoutMs = 1e4) {

package/dist/runtime/index.cjs

@@ -869,12 +869,19 @@ function getState() {
         checks: /* @__PURE__ */ new Map(),
         transitions: [],
         bridgeHealth: null,
-        listeners: /* @__PURE__ */ new Set()
+        listeners: /* @__PURE__ */ new Set(),
+        traitSnapshots: /* @__PURE__ */ new Map()
       };
     }
     return w.__verificationRegistryState;
   }
-  return { checks: /* @__PURE__ */ new Map(), transitions: [], bridgeHealth: null, listeners: /* @__PURE__ */ new Set() };
+  return {
+    checks: /* @__PURE__ */ new Map(),
+    transitions: [],
+    bridgeHealth: null,
+    listeners: /* @__PURE__ */ new Set(),
+    traitSnapshots: /* @__PURE__ */ new Map()
+  };
 }
 function notifyListeners2() {
   getState().listeners.forEach((l) => l());
@@ -981,9 +988,21 @@ function getSnapshot2() {
     checks: getAllChecks(),
     transitions: getTransitions(),
     bridge: getBridgeHealth(),
-    summary: getSummary()
+    summary: getSummary(),
+    traits: getTraitSnapshots()
   };
 }
+function getTraitSnapshots() {
+  const snapshots = [];
+  for (const [traitName, getter] of getState().traitSnapshots.entries()) {
+    try {
+      snapshots.push(getter());
+    } catch (err) {
+      log2.error("traitSnapshot getter failed", { trait: traitName, err: String(err) });
+    }
+  }
+  return snapshots;
+}
 function subscribeToVerification(listener) {
   getState().listeners.add(listener);
   return () => getState().listeners.delete(listener);
@@ -997,8 +1016,11 @@ function exposeOnWindow() {
       getTransitions,
       getBridge: getBridgeHealth,
       getSummary,
-      waitForTransition
+      waitForTransition,
+      getTraitSnapshots
     };
+  } else if (!window.__orbitalVerification.getTraitSnapshots) {
+    window.__orbitalVerification.getTraitSnapshots = getTraitSnapshots;
   }
 }
 function waitForTransition(event, timeoutMs = 1e4) {

package/dist/runtime/index.js

@@ -824,12 +824,19 @@ function getState() {
         checks: /* @__PURE__ */ new Map(),
         transitions: [],
         bridgeHealth: null,
-        listeners: /* @__PURE__ */ new Set()
+        listeners: /* @__PURE__ */ new Set(),
+        traitSnapshots: /* @__PURE__ */ new Map()
       };
     }
     return w.__verificationRegistryState;
   }
-  return { checks: /* @__PURE__ */ new Map(), transitions: [], bridgeHealth: null, listeners: /* @__PURE__ */ new Set() };
+  return {
+    checks: /* @__PURE__ */ new Map(),
+    transitions: [],
+    bridgeHealth: null,
+    listeners: /* @__PURE__ */ new Set(),
+    traitSnapshots: /* @__PURE__ */ new Map()
+  };
 }
 function notifyListeners2() {
   getState().listeners.forEach((l) => l());
@@ -936,9 +943,21 @@ function getSnapshot2() {
     checks: getAllChecks(),
     transitions: getTransitions(),
     bridge: getBridgeHealth(),
-    summary: getSummary()
+    summary: getSummary(),
+    traits: getTraitSnapshots()
   };
 }
+function getTraitSnapshots() {
+  const snapshots = [];
+  for (const [traitName, getter] of getState().traitSnapshots.entries()) {
+    try {
+      snapshots.push(getter());
+    } catch (err) {
+      log2.error("traitSnapshot getter failed", { trait: traitName, err: String(err) });
+    }
+  }
+  return snapshots;
+}
 function subscribeToVerification(listener) {
   getState().listeners.add(listener);
   return () => getState().listeners.delete(listener);
@@ -952,8 +971,11 @@ function exposeOnWindow() {
       getTransitions,
       getBridge: getBridgeHealth,
       getSummary,
-      waitForTransition
+      waitForTransition,
+      getTraitSnapshots
     };
+  } else if (!window.__orbitalVerification.getTraitSnapshots) {
+    window.__orbitalVerification.getTraitSnapshots = getTraitSnapshots;
   }
 }
 function waitForTransition(event, timeoutMs = 1e4) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/ui",
-  "version": "3.1.3",
+  "version": "3.2.0",
   "description": "React UI components, hooks, and providers for Almadar",
   "type": "module",
   "main": "./dist/components/index.js",