@rtsdk/topia 0.17.7 → 0.17.9

package/dist/index.js

@@ -39708,14 +39708,44 @@ class SDKController {
     }
 }
 
+/* ============================================================================
+AI RULES for code assistants
+
+  CONTEXT
+    - "Controllers" expose operations on domain objects (e.g., Asset).
+    - Consumers obtain controller instances via factory methods (e.g., AssetFactory.get).
+
+  DO
+    - Expect consumers to import a pre-instantiated factory from their app (e.g., utils/topiaInit.ts).
+    - Use ONLY the methods defined & documented in this file's types/TSDoc.
+
+  DO NOT
+    - Do NOT suggest creating Topia clients or factories inside controllers.
+    - Do NOT suggest non-existent methods: getById, fetch, find
+    - Do NOT mutate controller shape or return ad-hoc fields.
+
+  CANONICAL USAGE (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, AssetFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const Asset = new AssetFactory(topia);
+
+    // controllers/myController.ts (consumer app)
+    import { Asset } from "utils/topiaInit.ts";
+    const asset = await Asset.create(assetId, { credentials });
+    await asset.fetchAssetById();
+
+============================================================================ */
 /**
  * Create an instance of Asset class with a given asset id and optional attributes and session credentials.
  *
  * @example
  * ```ts
- * const asset = await new Asset(topia, "id", {
+ * import { Asset } from "utils/topiaInit.ts";
+ *
+ * const asset = await Asset.create(assetId, {
  *   attributes: { assetName: "My Asset", isPublic: false },
- *   credentials: { interactiveNonce: "exampleNonce", assetId: "droppedAssetId", visitorId: 1, urlSlug: "exampleWorld" }
+ *   credentials: { interactivePublicKey: "examplePublicKey", interactiveNonce: "exampleNonce", assetId: "exampleDroppedAssetId", visitorId: 1, urlSlug: "exampleUrlSlug" }
  * });
  * ```
  */
@@ -39729,6 +39759,8 @@ class Asset extends SDKController {
     /**
      * Retrieves platform asset details and assigns response data to the instance.
      *
+     * @keywords get, fetch, retrieve, load, details, info, information
+     *
      * @example
      * ```ts
      * await asset.fetchAssetById();
@@ -39752,6 +39784,8 @@ class Asset extends SDKController {
     /**
      * Updates platform asset details.
      *
+     * @keywords update, modify, change, edit, alter, transform
+     *
      * @example
      * ```ts
      * await asset.updateAsset({
@@ -39845,14 +39879,43 @@ const scatterVisitors = (original, scatterBy) => {
 };
 
 var _DroppedAsset_updateDroppedAsset;
+/* ============================================================================
+AI RULES for code assistants
+
+  CONTEXT
+    - "Controllers" expose operations on domain objects (e.g., DroppedAsset).
+    - Consumers obtain controller instances via factory methods (e.g., DroppedAssetFactory.get).
+
+  DO
+    - Expect consumers to import a pre-instantiated factory from their app (e.g., utils/topiaInit.ts).
+    - Use ONLY the methods defined & documented in this file's types/TSDoc.
+
+  DO NOT
+    - Do NOT suggest creating Topia clients or factories inside controllers.
+    - Do NOT suggest non-existent methods: getById, fetch, find
+    - Do NOT mutate controller shape or return ad-hoc fields.
+
+  CANONICAL USAGE (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, DroppedAssetFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const DroppedAsset = new DroppedAssetFactory(topia);
+
+    // controllers/myController.ts (consumer app)
+    import { DroppedAsset } from "utils/topiaInit.ts";
+    const da = await DroppedAsset.get(droppedAssetId, urlSlug, { credentials });
+    await da.fetchDataObject();
+
+============================================================================ */
 /**
  * Create an instance of Dropped Asset class with a given dropped asset id, url slug, and optional attributes and session credentials.
  *
  * @example
  * ```ts
- * const droppedAsset = await new DroppedAsset(topia, "1giFZb0sQ3X27L7uGyQX", "example", {
- *   attributes: { text: "My Dropped Asset" },
- *   credentials: { interactiveNonce: "exampleNonce", assetId: "droppedAssetId", visitorId: 1, urlSlug: "exampleWorld" }
+ * import { DroppedAsset } from "utils/topiaInit.ts";
+ *
+ * const droppedAsset = await DroppedAsset.get(exampleDroppedAssetId, exampleUrlSlug, {
+ *   credentials: { interactivePublicKey: "examplePublicKey", interactiveNonce: "exampleNonce", assetId: "exampleDroppedAssetId", visitorId: 1, urlSlug: "exampleUrlSlug" }
  * });
  * ```
  */
@@ -39880,6 +39943,8 @@ class DroppedAsset extends Asset {
     /**
      * Retrieves dropped asset details and assigns response data to the instance.
      *
+     * @keywords get, fetch, retrieve, load, details, info, information
+     *
      * @example
      * ```ts
      * await droppedAsset.fetchDroppedAssetById();
@@ -39902,6 +39967,8 @@ class DroppedAsset extends Asset {
     /**
      * Updates dropped asset details and assigns the response data to the instance. Requires Public Key to have the `canUpdateDroppedAssets` permission.
      *
+     * @keywords update, modify, change, edit, alter, transform
+     *
      * @example
      * ```ts
      * const payload = {
@@ -39976,6 +40043,8 @@ class DroppedAsset extends Asset {
     /**
      * Deletes the dropped asset (removes it from the world).
      *
+     * @keywords remove, delete, erase, destroy, eliminate
+     *
      * @example
      * ```ts
      * await droppedAsset.deleteDroppedAsset();
@@ -39994,6 +40063,8 @@ class DroppedAsset extends Asset {
     /**
      * Retrieves the data object for a dropped asset.
      *
+     * @keywords get, fetch, retrieve, load, data, object, state
+     *
      * @category Data Objects
      *
      * @example
@@ -40026,6 +40097,8 @@ class DroppedAsset extends Asset {
      * @remarks
      * Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
      *
+     * @keywords set, assign, store, save, data, object, state
+     *
      * @category Data Objects
      *
      * @example
@@ -40058,6 +40131,8 @@ class DroppedAsset extends Asset {
      * @remarks
      * Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
      *
+     * @keywords update, modify, change, edit, alter, data, object, state
+     *
      * @category Data Objects
      *
      * @example
@@ -40087,6 +40162,8 @@ class DroppedAsset extends Asset {
      * @remarks
      * Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
      *
+     * @keywords increment, increase, add, count, data, object, state
+     *
      * @category Data Objects
      *
      * @example
@@ -40111,6 +40188,8 @@ class DroppedAsset extends Asset {
     /**
      * Updates broadcast options for a dropped asset.
      *
+     * @keywords broadcast, dropped asset settings
+     *
      * @example
      * ```ts
      * await droppedAsset.updateBroadcast({
@@ -40134,6 +40213,8 @@ class DroppedAsset extends Asset {
     /**
      * Updates click options for a dropped asset.
      *
+     * @keywords click, link, interaction, url, dropped asset settings
+     *
      * @example
      * ```ts
      * await droppedAsset.updateClickType({
@@ -40174,6 +40255,8 @@ class DroppedAsset extends Asset {
     /**
      * Adds an array of links to an asset. Maximum is 20 links.
      *
+     * @keywords links, multiple, clickable, urls, hyperlinks, dropped asset settings
+     *
      * @example
      * ```ts
      * await droppedAsset.setClickableLinkMulti({
@@ -40214,6 +40297,8 @@ class DroppedAsset extends Asset {
      * @remarks
      * Pass in an 'existingLinkId' to edit an existing link.
      *
+     * @keywords links, multiple, clickable, urls, dropped asset settings
+     *
      * @example
      * ```ts
      * await droppedAsset.updateClickableLinkMulti({
@@ -40247,6 +40332,8 @@ class DroppedAsset extends Asset {
     /**
      * Removes a clickable link from a dropped asset.
      *
+     * @keywords remove, delete, link, clickable, url, erase, dropped asset settings
+     *
      * @example
      * ```ts
      * await droppedAsset.removeClickableLink({ linkId: "link-id" });
@@ -40268,6 +40355,8 @@ class DroppedAsset extends Asset {
     /**
      * Updates text and style of a dropped asset.
      *
+     * @keywords text, style, dropped asset settings
+     *
      * @example
      * ```ts
      * const style = {
@@ -40294,6 +40383,8 @@ class DroppedAsset extends Asset {
     /**
      * Updates media options for a dropped asset.
      *
+     * @keywords media, video, audio, dropped asset settings
+     *
      * @example
      * ```ts
      * await droppedAsset.updateMediaType({
@@ -40331,6 +40422,8 @@ class DroppedAsset extends Asset {
     /**
      * Updates mute zone options for a dropped asset.
      *
+     * @keywords mute, zone, dropped asset settings
+     *
      * @example
      * ```ts
      * await droppedAsset.updateMuteZone(true);
@@ -40349,6 +40442,8 @@ class DroppedAsset extends Asset {
     /**
      * Updates landmark zone options for a dropped asset.
      *
+     * @keywords landmark, zone, dropped asset settings
+     *
      * @example
      * ```ts
      * await droppedAsset.updateLandmarkZone({
@@ -40372,6 +40467,8 @@ class DroppedAsset extends Asset {
     /**
      * Updates webhook zone options for a dropped asset.
      *
+     * @keywords webhook, zone, dropped asset settings
+     *
      * @example
      * ```ts
      * await droppedAsset.updateWebhookZone(true);
@@ -40390,6 +40487,8 @@ class DroppedAsset extends Asset {
     /**
      * Moves a dropped asset to specified coordinates.
      *
+     * @keywords position, dropped asset settings
+     *
      * @example
      * ```ts
      * await droppedAsset.updatePosition(100, 200, 100);
@@ -40409,6 +40508,8 @@ class DroppedAsset extends Asset {
     /**
      * Updates private zone options for a dropped asset.
      *
+     * @keywords private, zone, dropped asset settings
+     *
      * @example
      * ```ts
      * await droppedAsset.updatePrivateZone({
@@ -40432,6 +40533,8 @@ class DroppedAsset extends Asset {
     /**
      * Updates the size of a dropped asset.
      *
+     * @keywords size, scale, dropped asset settings
+     *
      * @example
      * ```ts
      * await droppedAsset.assetScale(.5);
@@ -40450,6 +40553,8 @@ class DroppedAsset extends Asset {
     /**
      * Flip an dropped asset.
      *
+     * @keywords flip, layout, dropped asset settings
+     *
      * @example
      * ```ts
      * await droppedAsset.flip(.5);
@@ -40468,6 +40573,8 @@ class DroppedAsset extends Asset {
     /**
      * Change or remove media embedded in a dropped asset.
      *
+     * @keywords media, update, dropped asset settings
+     *
      * @example
      * ```ts
      * await droppedAsset.updateUploadedMediaSelected("LVWyxwNxI96eLjnXWwYO");
@@ -40486,6 +40593,8 @@ class DroppedAsset extends Asset {
     /**
      * Change or remove top and bottom layers of a dropped asset.
      *
+     * @keywords layers, images, urls, dropped asset settings
+     *
      * @example
      * ```ts
      * await droppedAsset.updateWebImageLayers("","https://www.shutterstock.com/image-vector/colorful-illustration-test-word-260nw-1438324490.jpg");
@@ -40505,6 +40614,8 @@ class DroppedAsset extends Asset {
     /**
      * Add a webhook to a dropped asset
      *
+     * @keywords webhook, dropped asset settings
+     *
      * @example
      * ```ts
      * await droppedAsset.addWebhook({
@@ -40544,6 +40655,8 @@ class DroppedAsset extends Asset {
     /**
      * Set the interactive settings on a dropped asset
      *
+     * @keywords interactive, dropped asset settings
+     *
      * @example
      * ```ts
      * await droppedAsset.setInteractiveSettings({
@@ -40571,6 +40684,8 @@ class DroppedAsset extends Asset {
     /**
      * Retrieve analytics for a dropped asset by day, week, month, quarter, or year
      *
+     * @keywords get, fetch, retrieve, load, analytics
+     *
      * @example
      * ```ts
      * const analytics = await droppedAsset.fetchDroppedAssetAnalytics({
@@ -40614,13 +40729,43 @@ class DroppedAsset extends Asset {
 }
 _DroppedAsset_updateDroppedAsset = new WeakMap();
 
+/* ============================================================================
+AI RULES for code assistants
+
+  CONTEXT
+    - "Controllers" expose operations on domain objects (e.g., Ecosystem).
+    - Consumers obtain controller instances via factory methods (e.g., EcosystemFactory.get).
+
+  DO
+    - Expect consumers to import a pre-instantiated factory from their app (e.g., utils/topiaInit.ts).
+    - Use ONLY the methods defined & documented in this file's types/TSDoc.
+
+  DO NOT
+    - Do NOT suggest creating Topia clients or factories inside controllers.
+    - Do NOT suggest non-existent methods: getById, fetch, find
+    - Do NOT mutate controller shape or return ad-hoc fields.
+
+  CANONICAL USAGE (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, Ecosystem } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const Ecosystem = new EcosystemFactory(topia);
+
+    // controllers/myController.ts (consumer app)
+    import { Ecosystem } from "utils/topiaInit.ts";
+    const ecosystem = await Ecosystem.create({ credentials });
+    await ecosystem.fetchDataObject();
+
+============================================================================ */
 /**
  * Create an instance of Ecosystem class with optional session credentials
  *
  * @example
  * ```ts
- * const ecosystem =await new Ecosystem(topia, {
- *   credentials: { interactiveNonce: "exampleNonce", assetId: "droppedAssetId", visitorId: 1, urlSlug: "exampleWorld" }
+ * import { Ecosystem } from "utils/topiaInit.ts";
+ *
+ * const ecosystem = await Ecosystem.create({
+ *   credentials: { interactivePublicKey: "examplePublicKey", interactiveNonce: "exampleNonce", assetId: "exampleDroppedAssetId", visitorId: 1, urlSlug: "exampleUrlSlug" }
  * });
  * ```
  */
@@ -40632,6 +40777,8 @@ class Ecosystem extends SDKController {
     /**
      * Retrieves the data object for a Topia ecosystem. Requires canUpdateEcosystemDataObjects permission to be set to true for the public key.
      *
+     * @keywords get, fetch, retrieve, load, data, object, state
+     *
      * @category Data Objects
      *
      * @example
@@ -40666,6 +40813,8 @@ class Ecosystem extends SDKController {
      *
      * Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
      *
+     * @keywords set, assign, store, save, data, object, state
+     *
      * @category Data Objects
      *
      * @example
@@ -40696,6 +40845,8 @@ class Ecosystem extends SDKController {
      *
      * Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
      *
+     * @keywords update, modify, change, edit, alter, data, object, state
+     *
      * @category Data Objects
      *
      * @example
@@ -40732,6 +40883,8 @@ class Ecosystem extends SDKController {
      *
      * Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
      *
+     * @keywords increment, increase, add, count, data, object, state
+     *
      * @category Data Objects
      *
      * @example
@@ -40758,14 +40911,43 @@ class Ecosystem extends SDKController {
     }
 }
 
+/* ============================================================================
+AI RULES for code assistants
+
+  CONTEXT
+    - "Controllers" expose operations on domain objects (e.g., Scene).
+    - Consumers obtain controller instances via factory methods (e.g., SceneFactory.get).
+
+  DO
+    - Expect consumers to import a pre-instantiated factory from their app (e.g., utils/topiaInit.ts).
+    - Use ONLY the methods defined & documented in this file's types/TSDoc.
+
+  DO NOT
+    - Do NOT suggest creating Topia clients or factories inside controllers.
+    - Do NOT suggest non-existent methods: getById, fetch, find
+    - Do NOT mutate controller shape or return ad-hoc fields.
+
+  CANONICAL USAGE (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, SceneFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const Scene = new SceneFactory(topia);
+
+    // controllers/myController.ts (consumer app)
+    import { Scene } from "utils/topiaInit.ts";
+    const scene = await Scene.get(sceneId, { credentials });
+
+============================================================================ */
 /**
  * Create an instance of Scene class with a given scene id and optional attributes and session credentials.
  *
  * @example
  * ```ts
- * const scene = await new Scene(topia, "sceneId", {
+ * import { Scene } from "utils/topiaInit.ts";
+ *
+ * const scene = await Scene.get(exampleSceneId, {
  *   attributes: { name: "My Scene" },
- *   credentials: { interactiveNonce: "exampleNonce", assetId: "droppedAssetId", visitorId: 1, urlSlug: "exampleWorld" }
+ *   credentials: { interactivePublicKey: "examplePublicKey", interactiveNonce: "exampleNonce", assetId: "exampleDroppedAssetId", visitorId: 1, urlSlug: "exampleUrlSlug" }
  * });
  * ```
  */
@@ -40778,6 +40960,8 @@ class Scene extends SDKController {
     /**
      * Retrieves scene details and assigns response data to the instance.
      *
+     * @keywords get, fetch, retrieve, load, details, info, information, scene
+     *
      * @example
      * ```ts
      * await scene.fetchSceneById();
@@ -40835,14 +41019,44 @@ class Topia {
 }
 
 var _World_droppedAssetsMap;
+/* ============================================================================
+AI RULES for code assistants
+
+  CONTEXT
+    - "Controllers" expose operations on domain objects (e.g., World).
+    - Consumers obtain controller instances via factory methods (e.g., WorldFactory.get).
+
+  DO
+    - Expect consumers to import a pre-instantiated factory from their app (e.g., utils/topiaInit.ts).
+    - Use ONLY the methods defined & documented in this file's types/TSDoc.
+
+  DO NOT
+    - Do NOT suggest creating Topia clients or factories inside controllers.
+    - Do NOT suggest non-existent methods: getById, fetch, find
+    - Do NOT mutate controller shape or return ad-hoc fields.
+
+  CANONICAL USAGE (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, WorldFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const World = new WorldFactory(topia);
+
+    // controllers/myController.ts (consumer app)
+    import { World } from "utils/topiaInit.ts";
+    const world = await World.create(urlSlug, { credentials });
+    await world.fetchDetails();
+
+============================================================================ */
 /**
  * Create an instance of World class with a given url slug and optional attributes and session credentials.
  *
  * @example
  * ```ts
- * const world = await new World(topia, "exampleWorld", {
+ * import { World } from "utils/topiaInit.ts";
+ *
+ * const world = await World.create(exampleUrlSlug, {
  *   attributes: { name: "Example World" },
- *   credentials: { interactiveNonce: "exampleNonce", assetId: "droppedAssetId", visitorId: 1, urlSlug: "exampleWorld" }
+ *   credentials: { interactivePublicKey: "examplePublicKey", interactiveNonce: "exampleNonce", assetId: "exampleDroppedAssetId", visitorId: 1, urlSlug: "exampleUrlSlug" }
  * });
  * ```
  */
@@ -40855,6 +41069,8 @@ class World extends SDKController {
         /**
          * Retrieves the data object for a world. Must have valid interactive credentials from a visitor in the world.
          *
+         * @keywords get, fetch, retrieve, load, data, object, state
+         *
          * @category Data Objects
          *
          * @example
@@ -40884,6 +41100,8 @@ class World extends SDKController {
          * @remarks
          * Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
          *
+         * @keywords set, assign, store, save, data, object, state
+         *
          * @category Data Objects
          *
          * @example
@@ -40913,6 +41131,8 @@ class World extends SDKController {
          * @remarks
          * Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
          *
+         * @keywords update, modify, change, edit, alter, data, object, state
+         *
          * @category Data Objects
          *
          * @example
@@ -40944,6 +41164,8 @@ class World extends SDKController {
     /**
      * Retrieves details of a world.
      *
+     * @keywords get, fetch, retrieve, details, info, information, world
+     *
      * @example
      * ```ts
      * await world.fetchDetails();
@@ -40964,6 +41186,8 @@ class World extends SDKController {
     /**
      * Update details of a world.
      *
+     * @keywords update, modify, change, edit, world, settings, details
+     *
      * @example
      * ```ts
      * await world.updateDetails({
@@ -41008,6 +41232,8 @@ class World extends SDKController {
     /**
      * Set close world settings
      *
+     * @keywords update, modify, change, edit, world, settings, details, close, closed
+     *
      * @example
      * ```ts
      * await world.updateCloseWorldSettings({
@@ -41047,6 +41273,8 @@ class World extends SDKController {
     /**
      * Retrieve all assets dropped in a world.
      *
+     * @keywords get, fetch, retrieve, list, current, dropped assets
+     *
      * @category Dropped Assets
      *
      * @example
@@ -41077,6 +41305,8 @@ class World extends SDKController {
     /**
      * Retrieve all assets dropped in a world matching uniqueName.
      *
+     * @keywords get, fetch, retrieve, list, current, dropped assets, uniqueName
+     *
      * @category Dropped Assets
      *
      * @example
@@ -41111,6 +41341,8 @@ class World extends SDKController {
     /**
      * Retrieve all assets dropped in a world matching sceneDropId.
      *
+     * @keywords get, fetch, retrieve, list, current, dropped assets, sceneDropId
+     *
      * @category Dropped Assets
      *
      * @example
@@ -41151,6 +41383,8 @@ class World extends SDKController {
     /**
      * Update multiple custom text dropped assets with a single style while preserving text for specified dropped assets only.
      *
+     * @keywords update, modify, change, edit, dropped assets, custom text, style, text
+     *
      * @category Dropped Assets
      *
      * @example
@@ -41182,6 +41416,8 @@ class World extends SDKController {
     /**
      * Retrieve all landmark zone assets dropped in a world.
      *
+     * @keywords get, fetch, retrieve, list, landmark, zones, dropped assets
+     *
      * @category Dropped Assets
      *
      * @example
@@ -41253,6 +41489,8 @@ class World extends SDKController {
     /**
      * Fetch a list of all scene drop ids and dropped assets in a world
      *
+     * @keywords get, fetch, retrieve, list, scenes
+     *
      * @category Scenes
      *
      * @example
@@ -41294,6 +41532,8 @@ class World extends SDKController {
     /**
      * Drops a scene in a world and returns sceneDropId.
      *
+     * @keywords drop, add, place, scene
+     *
      * @category Scenes
      *
      * @example
@@ -41328,6 +41568,8 @@ class World extends SDKController {
     /**
      * Replace the current scene of a world.
      *
+     * @keywords replace, change, scene
+     *
      * @category Scenes
      *
      * @example
@@ -41358,6 +41600,8 @@ class World extends SDKController {
     /**
      * Get all particles available
      *
+     * @keywords get, fetch, retrieve, list, particles
+     *
      * @category Particles
      *
      * @example
@@ -41381,6 +41625,8 @@ class World extends SDKController {
     /**
      * Trigger a particle effect at a position in the world
      *
+     * @keywords trigger, start, play, particle, effect
+     *
      * @category Particles
      *
      * @example
@@ -41417,6 +41663,8 @@ class World extends SDKController {
      * Add an activity to a world
      * excludeFromNotification is an array of visitorIds to exclude from the notification
      *
+     * @keywords start, trigger, activity
+     *
      * @example
      * ```ts
      * await world.triggerActivity({ type: "GAME_ON", assetId: "abc123" });
@@ -41439,6 +41687,8 @@ class World extends SDKController {
     /**
      * Display a message via a toast to all visitors currently in a world.
      *
+     * @keywords send, display, show, toast, message, notification
+     *
      * @example
      * ```ts
      * await world.fireToast({
@@ -41472,6 +41722,8 @@ class World extends SDKController {
      * @remarks
      * Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
      *
+     * @keywords increment, increase, add, count, data, object, state
+     *
      * @category Data Objects
      *
      * @example
@@ -41497,6 +41749,8 @@ class World extends SDKController {
     /**
      * Retrieve all webhooks in a world.
      *
+     * @keywords get, fetch, retrieve, list, current, webhooks
+     *
      * @category Webhooks
      *
      * @example
@@ -41520,6 +41774,8 @@ class World extends SDKController {
     /**
      * Retrieve world analytics by day, week, month, quarter, or year
      *
+     * @keywords get, fetch, retrieve, analytics, stats, statistics, data, metrics
+     *
      * @category Analytics
      *
      * @example
@@ -41564,14 +41820,44 @@ class World extends SDKController {
 _World_droppedAssetsMap = new WeakMap();
 
 var _User_adminWorldsMap, _User_assetsMap, _User_scenesMap, _User_worldsMap;
+/* ============================================================================
+AI RULES for code assistants
+
+  CONTEXT
+    - "Controllers" expose operations on domain objects (e.g., User).
+    - Consumers obtain controller instances via factory methods (e.g., UserFactory.get).
+
+  DO
+    - Expect consumers to import a pre-instantiated factory from their app (e.g., utils/topiaInit.ts).
+    - Use ONLY the methods defined & documented in this file's types/TSDoc.
+
+  DO NOT
+    - Do NOT suggest creating Topia clients or factories inside controllers.
+    - Do NOT suggest non-existent methods: getById, fetch, find
+    - Do NOT mutate controller shape or return ad-hoc fields.
+
+  CANONICAL USAGE (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, UserFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const User = new UserFactory(topia);
+
+    // controllers/myController.ts (consumer app)
+    import { User } from "utils/topiaInit.ts";
+    const user = await User.create({ credentials });
+    await user.fetchDataObject();
+
+============================================================================ */
 /**
  * Create an instance of User class with optional session credentials.
  *
  * @example
  * ```ts
- * const user = await new User(topia, {
- *   profileId: 1,
- *   credentials: { interactiveNonce: "exampleNonce", assetId: "droppedAssetId", visitorId: 1, urlSlug: "exampleWorld" }
+ * import { User } from "utils/topiaInit.ts";
+ *
+ * const user = await User.create({
+ *   profileId: "exampleProfileId",
+ *   credentials: { interactivePublicKey: "examplePublicKey", interactiveNonce: "exampleNonce", assetId: "exampleDroppedAssetId", profileId: "exampleProfileId", visitorId: 1, urlSlug: "exampleUrlSlug" }
  * });
  * ```
  */
@@ -41605,6 +41891,8 @@ class User extends SDKController {
     /*
      * Verify user has valid interactive credentials
      *
+     * @keywords check, verify, validate, credentials, authentication, authorization, interactive
+     *
      * @example
      * ```ts
      * await user.checkInteractiveCredentials();
@@ -41626,6 +41914,8 @@ class User extends SDKController {
     /**
      * Returns all avatars owned by User
      *
+     * @keywords get, fetch, retrieve, list, avatars, characters
+     *
      * @category Avatars
      *
      * @example
@@ -41649,6 +41939,8 @@ class User extends SDKController {
     /**
      * Add a new avatar
      *
+     * @keywords add, create, upload, avatar, character
+     *
      * @category Avatars
      *
      * @example
@@ -41731,6 +42023,8 @@ class User extends SDKController {
     /**
      * Update avatar and sprite sheet records and upload files to existing sprite sheet and avatar storage buckets
      *
+     * @keywords update, modify, change, edit, avatar, character
+     *
      * @category Avatars
      *
      * @example
@@ -41813,6 +42107,8 @@ class User extends SDKController {
     /**
      * Update avatar and sprite sheet records and upload files to existing sprite sheet and avatar storage buckets
      *
+     * @keywords delete, remove, erase, destroy, eliminate, avatar
+     *
      * @category Avatars
      *
      * @example
@@ -41834,6 +42130,8 @@ class User extends SDKController {
     /**
      * Returns all assets owned by User when an email address is provided.
      *
+     * @keywords get, fetch, retrieve, list, user assets, objects
+     *
      * @category Assets
      *
      * @example
@@ -41864,6 +42162,8 @@ class User extends SDKController {
     /**
      * Returns all platform assets.
      *
+     * @keywords get, fetch, retrieve, list, platform assets, objects
+     *
      * @category Assets
      *
      * @example
@@ -41887,6 +42187,8 @@ class User extends SDKController {
     /**
      * Returns all scenes owned by User.
      *
+     * @keywords get, fetch, retrieve, list, user scenes
+     *
      * @category Scenes
      *
      * @example
@@ -41917,6 +42219,8 @@ class User extends SDKController {
     /**
      * Retrieves all worlds owned by user with matching API Key, creates a new World object for each, and creates new map of Worlds accessible via user.worlds.
      *
+     * @keywords get, fetch, retrieve, list, user worlds
+     *
      * @category Worlds
      *
      * @example
@@ -41952,6 +42256,8 @@ class User extends SDKController {
     /**
      * Retrieves all worlds a user with matching API Key is an admin in, creates a new World object for each, and creates new map of Worlds accessible via user.adminWorlds.
      *
+     * @keywords get, fetch, retrieve, list, admin worlds, user worlds
+     *
      * @category Worlds
      *
      * @example
@@ -41981,6 +42287,8 @@ class User extends SDKController {
     /**
      * Retrieves ids of all dropped assets in all worlds with a matching interactivePublicKey.
      *
+     * @keywords get, fetch, retrieve, list, interactive worlds, public key
+     *
      * @category Dropped Assets
      *
      * @example
@@ -42005,6 +42313,8 @@ class User extends SDKController {
     /**
      * Send an email
      *
+     * @keywords send, email, message, notify
+     *
      * @example
      * ```ts
      * const html = `<p><b>Hello World!</b></p><p>This email is being sent from via SDK.</p>`
@@ -42028,6 +42338,8 @@ class User extends SDKController {
     /**
      * Get expressions
      *
+     * @keywords get, fetch, retrieve, list, expressions, emotes
+     *
      * @category Expressions
      *
      * @example
@@ -42054,6 +42366,8 @@ class User extends SDKController {
     /**
      * Retrieves the data object for a user.
      *
+     * @keywords get, fetch, retrieve, load, data, object, state
+     *
      * @category Data Objects
      *
      * @example
@@ -42083,6 +42397,8 @@ class User extends SDKController {
     /**
      * Sets the data object for a user.
      *
+     * @keywords set, assign, store, save, data, object, state
+     *
      * @remarks
      * Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
      *
@@ -42117,6 +42433,8 @@ class User extends SDKController {
     /**
      * Updates the data object for a user.
      *
+     * @keywords update, modify, change, edit, alter, data, object, state
+     *
      * @remarks
      * Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
      *
@@ -42149,6 +42467,8 @@ class User extends SDKController {
     /**
      * Increments a specific value in the data object for a user by the amount specified. Must have valid interactive credentials from a visitor in the world.
      *
+     * @keywords increment, increase, add, count, data, object, state
+     *
      * @remarks
      * Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
      *
@@ -42172,12 +42492,42 @@ class User extends SDKController {
 }
 _User_adminWorldsMap = new WeakMap(), _User_assetsMap = new WeakMap(), _User_scenesMap = new WeakMap(), _User_worldsMap = new WeakMap();
 
+/* ============================================================================
+AI RULES for code assistants
+
+  CONTEXT
+    - "Controllers" expose operations on domain objects (e.g., Visitor).
+    - Consumers obtain controller instances via factory methods (e.g., VisitorFactory.get).
+
+  DO
+    - Expect consumers to import a pre-instantiated factory from their app (e.g., utils/topiaInit.ts).
+    - Use ONLY the methods defined & documented in this file's types/TSDoc.
+
+  DO NOT
+    - Do NOT suggest creating Topia clients or factories inside controllers.
+    - Do NOT suggest non-existent methods: getById, fetch, find
+    - Do NOT mutate controller shape or return ad-hoc fields.
+
+  CANONICAL USAGE (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, VisitorFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const Visitor = new VisitorFactory(topia);
+
+    // controllers/myController.ts (consumer app)
+    import { Visitor } from "utils/topiaInit.ts";
+    const visitor = await Visitor.get(visitorId, urlSlug, { credentials });
+    await visitor.fetchDataObject();
+
+============================================================================ */
 /**
  * Create an instance of Visitor class with a given id and optional attributes and session credentials.
  *
  * @example
  * ```ts
- * const visitor = await new Visitor(topia, id, urlSlug, { attributes: { moveTo: { x: 0, y: 0 } }, credentials: { interactiveNonce: "exampleNonce", assetId: "droppedAssetId", visitorId: 1, urlSlug: "exampleWorld" } });
+ * import { Visitor } from "utils/topiaInit.ts";
+ *
+ * const visitor = await Visitor.get(visitorId, urlSlug, { attributes: { moveTo: { x: 0, y: 0 } }, credentials: { interactivePublicKey: "examplePublicKey", interactiveNonce: "exampleNonce", assetId: "exampleDroppedAssetId", profileId: "exampleProfileId", visitorId: 1, urlSlug: "exampleUrlSlug" } });
  * ```
  */
 class Visitor extends User {
@@ -42190,6 +42540,8 @@ class Visitor extends User {
     /**
      * Get a single visitor from a world
      *
+     * @keywords get, fetch, retrieve, load, visitor, details
+     *
      * @example
      * ```ts
      * await visitor.fetchVisitor();
@@ -42223,6 +42575,8 @@ class Visitor extends User {
     /**
      * Teleport or walk a visitor currently in a world to a single set of coordinates.
      *
+     * @keywords move, teleport, walk, position, coordinate, location, place
+     *
      * @example
      * ```ts
      * await visitor.moveVisitor({
@@ -42255,6 +42609,8 @@ class Visitor extends User {
     /**
      * Display a message via a toast to a visitor currently in a world.
      *
+     * @keywords toast, message, notification, alert, display, show, popup
+     *
      * @example
      * ```ts
      * await visitor.fireToast({
@@ -42285,6 +42641,8 @@ class Visitor extends User {
     /**
      * Open an iframe in a drawer or modal for a visitor currently in a world.
      *
+     * @keywords open, iframe, drawer, modal, link, url, website, web page
+     *
      * @category iframes
      *
      * @example
@@ -42319,6 +42677,8 @@ class Visitor extends User {
     /**
      * Reload an iframe for a visitor currently in a world.
      *
+     * @keywords reload, iframe, drawer, modal, link, url, website, web page
+     *
      * @category iframes
      *
      * @example
@@ -42342,6 +42702,8 @@ class Visitor extends User {
     /**
      * Close an iframe for a visitor currently in a world.
      *
+     * @keywords close, iframe, drawer, modal
+     *
      * @category iframes
      *
      * @example
@@ -42365,6 +42727,8 @@ class Visitor extends User {
     /**
      * Mute and turn video off for a visitor currently in a world.
      *
+     * @keywords mute, video, av, turn off, disable
+     *
      * @example
      * ```ts
      * await visitor.turnAVOff();
@@ -42386,6 +42750,8 @@ class Visitor extends User {
     /**
      * Get expressions
      *
+     * @keywords get, fetch, retrieve, list, expressions, emotes
+     *
      * @category Expressions
      *
      * @example
@@ -42411,6 +42777,8 @@ class Visitor extends User {
     /**
      * Grant expression to a visitor by id or name.
      *
+     * @keywords grant, give, add, expression, emote
+     *
      * @category Expressions
      *
      * @example
@@ -42442,6 +42810,8 @@ class Visitor extends User {
     /**
      * Get all particles available
      *
+     * @keywords get, fetch, retrieve, list, particles, effects
+     *
      * @category Particle Effects
      *
      * @example
@@ -42465,6 +42835,8 @@ class Visitor extends User {
     /**
      * Trigger a particle effect on a visitor
      *
+     * @keywords trigger, particle, effect, spawn, start, play
+     *
      * @category Particle Effects
      *
      * @example
@@ -42498,6 +42870,8 @@ class Visitor extends User {
     /**
      * Retrieves the data object for a visitor.
      *
+     * @keywords get, fetch, retrieve, load, data, object, state
+     *
      * @category Data Objects
      *
      * @example
@@ -42527,6 +42901,8 @@ class Visitor extends User {
     /**
      * Sets the data object for a visitor.
      *
+     * @keywords set, assign, store, save, data, object, state
+     *
      * @remarks
      * Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
      *
@@ -42562,6 +42938,8 @@ class Visitor extends User {
      * @remarks
      * Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
      *
+     * @keywords update, modify, change, edit, alter, data, object, state
+     *
      * @category Data Objects
      *
      * @example
@@ -42592,6 +42970,8 @@ class Visitor extends User {
      * @remarks
      * Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
      *
+     * @keywords increment, increase, add, count, data, object, state
+     *
      * @category Data Objects
      *
      * @example
@@ -42616,6 +42996,8 @@ class Visitor extends User {
     /**
      * Update analytics for a given public key. Must have valid interactive credentials from a visitor in the world.
      *
+     * @keywords update, modify, change, edit, analytics, analytic, stats, statistics, data
+     *
      * @example
      * ```ts
      * await visitor.updatePublicKeyAnalytics([{ analyticName: "joins", profileId, uniqueKey: profileId, urlSlug }]);
@@ -42638,6 +43020,8 @@ class Visitor extends User {
     /**
      * Setup signal to visitor
      *
+     * @keywords signal, webrtc, answer, connect, p2p
+     *
      * @example
      * ```ts
      * await visitor.sendSignalToVisitor(iceServers);
@@ -42666,7 +43050,7 @@ class Visitor extends User {
  * @example
  * ```ts
  * const webRTC = await new WebRTCConnector(topia, {
- *   credentials: { interactiveNonce: "exampleNonce", assetId: "droppedAssetId", visitorId: 1, urlSlug: "exampleWorld" }
+ *   credentials: { interactivePublicKey: "examplePublicKey", interactiveNonce: "exampleNonce", assetId: "exampleDroppedAssetId", profileId: "exampleProfileId", visitorId: 1, urlSlug: "exampleUrlSlug" }
  * });
  * ```
  */
@@ -42700,6 +43084,34 @@ class WebRTCConnector extends SDKController {
 }
 
 var _WorldActivity_visitorsMap;
+/* ============================================================================
+AI RULES for code assistants
+
+  CONTEXT
+    - "Controllers" expose operations on domain objects (e.g., WorldActivity).
+    - Consumers obtain controller instances via factory methods (e.g., WorldActivityFactory.get).
+
+  DO
+    - Expect consumers to import a pre-instantiated factory from their app (e.g., utils/topiaInit.ts).
+    - Use ONLY the methods defined & documented in this file's types/TSDoc.
+
+  DO NOT
+    - Do NOT suggest creating Topia clients or factories inside controllers.
+    - Do NOT suggest non-existent methods: getById, fetch, find
+    - Do NOT mutate controller shape or return ad-hoc fields.
+
+  CANONICAL USAGE (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, WorldActivityFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const WorldActivity = new WorldActivityFactory(topia);
+
+    // controllers/myController.ts (consumer app)
+    import { WorldActivity } from "utils/topiaInit.ts";
+    const activity = await WorldActivity.create(urlSlug, { credentials });
+    await activity.currentVisitors();
+
+============================================================================ */
 /**
  * Create an instance of WorldActivity class with a given url slug and optional attributes and session credentials.
  *
@@ -42708,9 +43120,11 @@ var _WorldActivity_visitorsMap;
  *
  * @example
  * ```ts
- * const activity = await new WorldActivity(topia, "exampleWorld", {
+ * import { WorldActivity } from "utils/topiaInit.ts";
+ *
+ * const activity = await WorldActivity.create(urlSlug, {
  *   attributes: { name: "Example World" },
- *   credentials: { interactiveNonce: "exampleNonce", assetId: "droppedAssetId", visitorId: 1, urlSlug: "exampleWorld" }
+ *   credentials: { interactivePublicKey: "examplePublicKey", interactiveNonce: "exampleNonce", assetId: "exampleDroppedAssetId", visitorId: 1, urlSlug: "exampleUrlSlug" }
  * });
  * ```
  */
@@ -42757,6 +43171,8 @@ class WorldActivity extends SDKController {
     /**
      * Retrieve all visitors currently in a world.
      *
+     * @keywords get, fetch, retrieve, list, current, visitors, users, players
+     *
      * @category Visitors
      *
      * @example
@@ -42780,6 +43196,8 @@ class WorldActivity extends SDKController {
     /**
      * Retrieve all visitors currently in a Landmark Zone.
      *
+     * @keywords get, fetch, retrieve, list, zone, area, landmark, visitors, users
+     *
      * @category Visitors
      *
      * @example
@@ -42809,6 +43227,8 @@ class WorldActivity extends SDKController {
      * Optionally refetch visitors, teleport or walk visitors to new location,
      * and scatter visitors by any number so that they don't all move to the exact same location.
      *
+     * @keywords move, teleport, position, coordinate, visitors, users, relocate
+     *
      * @category Visitors
      *
      * @example
@@ -42845,6 +43265,8 @@ class WorldActivity extends SDKController {
     /**
      * Teleport or walk a list of visitors currently in a world to various coordinates.
      *
+     * @keywords move, teleport, position, coordinate, visitor, user, relocate
+     *
      * @category Visitors
      *
      * @example
@@ -42881,10 +43303,50 @@ class WorldActivity extends SDKController {
 }
 _WorldActivity_visitorsMap = new WeakMap();
 
+/* ============================================================================
+  AI RULES for code assistants
+
+  - Consumers MUST create a single Topia client in their app (e.g. utils/topiaInit.ts).
+  - Consumers MUST instantiate this factory ONCE using that client and RE-USE it.
+  - Controllers/services MUST import the app’s exported factory instance.
+  - Use ONLY methods defined in this file’s types and TSDoc.
+  - Methods that DO NOT exist and MUST NOT be suggested.
+
+  RIGHT ✅ Correct usage pattern (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, AssetFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const Asset = new AssetFactory(topia);
+
+  RIGHT ✅ Correct usage pattern (controller):
+    // controllers/myController.ts
+    import { Asset } from "utils/topiaInit.ts";
+    const asset = await Asset.create(assetId, { credentials });
+    await asset.fetchAssetById();
+
+  WRONG ❌ Incorrect usage pattern (controller):
+    // controllers/myController.ts
+    import { AssetFactory, Topia } from "@rtsdk/topia";
+    const topia = new Topia(config); // ❌ new client per request
+    const Asset = new AssetFactory(topia); // ❌ ad-hoc factory
+    const asset = await Asset.getById(assetId); // ❌ method does not exist
+
+  Do NOT instantiate factories in controllers. Do NOT invent methods.
+============================================================================ */
 /**
+ * Factory for creating Asset instances. Use this factory to create or upload assets in the Topia platform.
+ *
+ * @remarks
+ * This factory should be instantiated once per application and reused across your codebase.
+ *
+ * @keywords asset, factory, create, upload, instantiate, topia
+ *
  * @example
  * ```ts
- * const Asset = new AssetFactory(myTopiaInstance);
+ * // In your initialization file (e.g., utils/topiaInit.ts)
+ * import { Topia, AssetFactory } from "@rtsdk/topia";
+ * const topia = new Topia({ config });
+ * export const Asset = new AssetFactory(topia);
  * ```
  */
 class AssetFactory extends SDKController {
@@ -42892,11 +43354,32 @@ class AssetFactory extends SDKController {
         super(topia);
     }
     /**
-     * Instantiate a new instance of Asset class.
+     * Instantiate a new instance of Asset class with the specified asset ID.
+     *
+     * @remarks
+     * This method creates a new Asset controller instance that can be used to interact with an existing asset.
+     * It does not create a new asset in the database.
+     *
+     * @keywords create, instantiate, asset, initialize, get, instance
      *
      * @example
-     * ```
-     * const assetInstance = await Asset.create(id, { credentials: { interactiveNonce, interactivePublicKey, assetId, urlSlug, visitorId } });
+     * ```ts
+     * // Import the pre-initialized factory from your app's initialization file
+     * import { Asset } from "utils/topiaInit.ts";
+     *
+     * // Create an Asset instance with credentials
+     * const assetInstance = await Asset.create(assetId, {
+     *   credentials: {
+     *     interactiveNonce,
+     *     interactivePublicKey,
+     *     assetId,
+     *     urlSlug,
+     *     visitorId
+     *   }
+     * });
+     *
+     * // Use the instance to interact with the asset
+     * await assetInstance.fetchAssetById();
      * ```
      *
      * @returns {Asset} Returns a new Asset object with the asset id.
@@ -42905,22 +43388,37 @@ class AssetFactory extends SDKController {
         return new Asset(this.topia, id, options);
     }
     /**
-     * Upload a new Asset and return a new instance of Asset class.
+     * Upload a new Asset to the Topia platform and return a new instance of Asset class.
+     *
+     * @remarks
+     * This method both creates a new asset in the database and returns an Asset controller instance.
+     * A valid API key with appropriate permissions is required.
+     *
+     * @keywords upload, create, new, asset, add, store
      *
      * @example
-     * ```
+     * ```ts
+     * // Import the pre-initialized factory from your app's initialization file
+     * import { Asset } from "utils/topiaInit.ts";
+     *
+     * // Prepare the asset payload
      * const assetPayload = {
-     *   assetName: "exampleAssetName"
-     *   bottomLayerURL: "https://example.bottomLayerURL"
+     *   assetName: "My Decorative Asset",
+     *   bottomLayerURL: "https://example.com/bottom-layer.png",
      *   creatorTags: { "decorations": true },
      *   tagJson: "[{"label":"decorations","value":"decorations"}]",
      *   isPublic: true,
-     *   topLayerURL: "https://example.topLayerURL"
-     * }
+     *   topLayerURL: "https://example.com/top-layer.png"
+     * };
+     *
+     * // Upload the asset using your API key
      * const asset = await Asset.upload(assetPayload, apiKey);
+     *
+     * // Access the new asset's properties
+     * console.log(asset.id);
      * ```
      *
-     * @returns {AssetType} Returns a new Asset object with the asset details.
+     * @returns {Asset} Returns a new Asset object with the asset details.
      */
     upload(assetPayload, apiKey) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -42939,10 +43437,50 @@ class AssetFactory extends SDKController {
     }
 }
 
+/* ============================================================================
+  AI RULES for code assistants
+
+  - Consumers MUST create a single Topia client in their app (e.g. utils/topiaInit.ts).
+  - Consumers MUST instantiate this factory ONCE using that client and RE-USE it.
+  - Controllers/services MUST import the app’s exported factory instance.
+  - Use ONLY methods defined in this file’s types and TSDoc.
+  - Methods that DO NOT exist and MUST NOT be suggested.
+
+  RIGHT ✅ Correct usage pattern (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, DroppedAssetFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const DroppedAsset = new DroppedAssetFactory(topia);
+
+  RIGHT ✅ Correct usage pattern (controller):
+    // controllers/myController.ts
+    import { DroppedAsset } from "utils/topiaInit.ts";
+    const da = await DroppedAsset.get(droppedAssetId, urlSlug, { credentials });
+    await da.fetchDataObject();
+
+  WRONG ❌ Incorrect usage pattern (controller):
+    // controllers/myController.ts
+    import { DroppedAssetFactory, Topia } from "@rtsdk/topia";
+    const topia = new Topia(config); // ❌ new client per request
+    const DroppedAsset = new DroppedAssetFactory(topia); // ❌ ad-hoc factory
+    const da = await DroppedAsset.getById(droppedAssetId); // ❌ method does not exist
+
+  Do NOT instantiate factories in controllers. Do NOT invent methods.
+============================================================================ */
 /**
+ * Factory for creating and retrieving DroppedAsset instances. Use this factory to work with assets that have been placed in a Topia world.
+ *
+ * @remarks
+ * This factory should be instantiated once per application and reused across your codebase.
+ *
+ * @keywords dropped asset, factory, create, get, retrieve, instantiate, topia
+ *
  * @example
  * ```ts
- * const DroppedAsset = new DroppedAssetFactory(myTopiaInstance);
+ * // In your initialization file (e.g., utils/topiaInit.ts)
+ * import { Topia, DroppedAssetFactory } from "@rtsdk/topia";
+ * const topia = new Topia({ config });
+ * export const DroppedAsset = new DroppedAssetFactory(topia);
  * ```
  */
 class DroppedAssetFactory extends SDKController {
@@ -42950,27 +43488,77 @@ class DroppedAssetFactory extends SDKController {
         super(topia);
     }
     /**
-     * Instantiate a new instance of DroppedAsset class.
+     * Instantiate a new instance of DroppedAsset class for an existing dropped asset in a world.
+     *
+     * @remarks
+     * This method creates a controller instance for an existing dropped asset but does not fetch its properties.
+     * Use this when you need a lightweight instance and will fetch properties separately if needed or when you already have the properties.
+     *
+     * @keywords create, instantiate, dropped asset, initialize, instance
      *
      * @example
-     * ```
-     * const droppedAssetInstance = await DroppedAsset.create(assetId, urlSlug, { credentials: { interactiveNonce, interactivePublicKey, assetId, urlSlug, visitorId } });
+     * ```ts
+     * // Import the pre-initialized factory from your app's initialization file
+     * import { DroppedAsset } from "utils/topiaInit.ts";
+     *
+     * // Create a DroppedAsset instance with credentials
+     * const droppedAssetInstance = DroppedAsset.create(
+     *   assetId,
+     *   urlSlug,
+     *   {
+     *     credentials: {
+     *       interactiveNonce,
+     *       interactivePublicKey,
+     *       assetId,
+     *       urlSlug,
+     *       visitorId
+     *     }
+     *   }
+     * );
+     *
+     * // Later fetch its properties if needed
+     * await droppedAssetInstance.fetchDroppedAssetById();
      * ```
      *
-     * @returns {DroppedAsset} Returns a new DroppedAsset object.
+     * @returns {DroppedAsset} Returns a new DroppedAsset object without fetching its properties.
      */
     create(id, urlSlug, options) {
         return new DroppedAsset(this.topia, id, urlSlug, options);
     }
     /**
-     * Instantiate a new instance of DroppedAsset class and retrieve all properties.
+     * Instantiate a new instance of DroppedAsset class and automatically fetch all its properties.
+     *
+     * @remarks
+     * This method creates a controller instance and immediately fetches all properties of the dropped asset.
+     * It's a convenience method that combines creating an instance and calling fetchDroppedAssetById().
+     *
+     * @keywords get, fetch, retrieve, dropped asset, load, instance
      *
      * @example
-     * ```
-     * const droppedAssetInstance = await DroppedAsset.get(assetId, urlSlug, { credentials: { interactiveNonce, interactivePublicKey, assetId, urlSlug, visitorId } });
+     * ```ts
+     * // Import the pre-initialized factory from your app's initialization file
+     * import { DroppedAsset } from "utils/topiaInit.ts";
+     *
+     * // Get a fully populated DroppedAsset instance
+     * const droppedAssetInstance = await DroppedAsset.get(
+     *   assetId,
+     *   urlSlug,
+     *   {
+     *     credentials: {
+     *       interactiveNonce,
+     *       interactivePublicKey,
+     *       assetId,
+     *       urlSlug,
+     *       visitorId
+     *     }
+     *   }
+     * );
+     *
+     * // The properties are already loaded, so you can use them immediately
+     * console.log(droppedAssetInstance.position);
      * ```
      *
-     * @returns {Promise<DroppedAsset>} Returns a new DroppedAsset object with all properties.
+     * @returns {Promise<DroppedAsset>} Returns a new DroppedAsset object with all properties already fetched.
      */
     get(id, urlSlug, options) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -42980,17 +43568,36 @@ class DroppedAssetFactory extends SDKController {
         });
     }
     /**
-     * Searches dropped assets within a world by a provide `uniqueName`. If a single match is found, a new instance of DroppedAsset class is returned all properties.
+     * Searches for and retrieves a dropped asset by its unique name within a world.
      *
      * @remarks
-     * This method leverages the handleGetDroppedAssetByUniqueName endpoint in the Public API and assumes there is exactly one dropped asset with matching uniqueName for the given urlSlug.
+     * This method leverages the handleGetDroppedAssetByUniqueName endpoint in the Public API and assumes there is exactly one dropped asset with the matching uniqueName for the given urlSlug.
+     * Use this when you need to find a dropped asset by its uniqueName rather than its ID.
+     *
+     * @keywords find, search, unique name, retrieve, locate, lookup, dropped asset
      *
      * @example
-     * ```
-     * const droppedAssetInstance = await DroppedAsset.getWithUniqueName("exampleUniqueName", urlSlug, interactiveSecret, credentials);
+     * ```ts
+     * // Import the pre-initialized factory from your app's initialization file
+     * import { DroppedAsset } from "utils/topiaInit.ts";
+     *
+     * // Find and retrieve a dropped asset by its unique name
+     * const droppedAssetInstance = await DroppedAsset.getWithUniqueName(
+     *   "banner-sign-northeast",
+     *   "my-world-slug",
+     *   "your-interactive-secret",
+     *   {
+     *     apiKey: "your-api-key",
+     *     interactivePublicKey: "your-public-key",
+     *     // other credentials...
+     *   }
+     * );
+     *
+     * // The properties are already loaded, so you can use them immediately
+     * console.log(droppedAssetInstance.position);
      * ```
      *
-     * @returns {Promise<DroppedAsset>} Returns a new DroppedAsset object with all properties.
+     * @returns {Promise<DroppedAsset>} Returns a new DroppedAsset object with all properties already fetched.
      */
     getWithUniqueName(uniqueName, urlSlug, interactiveSecret, credentials) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -43017,23 +43624,59 @@ class DroppedAssetFactory extends SDKController {
     /**
      * Drops an asset in a world and returns a new instance of DroppedAsset class with all properties.
      *
+     * @remarks
+     * This method places an existing Asset into a world at specified coordinates, effectively "dropping" it into the environment.
+     * You can customize various properties of the dropped asset during placement, such as scale, position, interactive settings, and visual layers.
+     *
+     * @keywords drop, place, add, create, position, asset, deploy
+     *
      * @example
-     * ```
-     * const assetInstance = await Asset.create(id, { credentials: { interactiveNonce, interactivePublicKey, assetId, urlSlug, visitorId } });
-     * const droppedAssetInstance = await DroppedAsset.get(assetInstance, {
-          assetScale: 1.5,
-          flipped: true,
-          layer0: "",
-          layer1: "https://pathtoimage.png",
-          interactivePublicKey,
-          isInteractive: true,
-          position: { x: 0, y: 0 },
-          uniqueName: "exampleUniqueName",
-          urlSlug,
-        });
+     * ```ts
+     * // Import the pre-initialized factories from your app's initialization file
+     * import { Asset, DroppedAsset } from "utils/topiaInit.ts";
+     *
+     * // First get an asset instance
+     * const assetInstance = Asset.create("asset-id-123", {
+     *   credentials: {
+     *     interactiveNonce,
+     *     interactivePublicKey,
+     *     assetId,
+     *     urlSlug,
+     *     visitorId
+     *   }
+     * });
+     *
+     * // Then drop (place) the asset in a world
+     * const droppedAssetInstance = await DroppedAsset.drop(
+     *   assetInstance,
+     *   {
+     *     // Basic positioning and appearance
+     *     position: { x: 250, y: 350 },
+     *     assetScale: 1.5,
+     *     flipped: true,
+     *     uniqueName: "welcome-sign",
+     *     urlSlug: "my-world-slug",
+     *
+     *     // For web images (optional)
+     *     layer0: "https://example.com/background.png",
+     *     layer1: "https://example.com/foreground.png",
+     *
+     *     // For interactive assets (optional)
+     *     interactivePublicKey: "your-public-key",
+     *     isInteractive: true,
+     *
+     *     // For clickable assets (optional)
+     *     clickType: "link",
+     *     clickableLink: "https://example.com",
+     *     clickableLinkTitle: "Visit Example"
+     *   }
+     * );
+     *
+     * // The dropped asset is ready to use
+     * console.log(droppedAssetInstance.id);
      * ```
      *
-     * @returns {Promise<DroppedAsset>} Returns a new DroppedAsset object with all properties.
+     * @returns {Promise<DroppedAsset>} Returns a new DroppedAsset object representing the placed asset in the world.
      */
     drop(asset, { assetScale = 1, clickType, clickableDisplayTextDescription, clickableDisplayTextHeadline, clickableLink, clickableLinkTitle, flipped, interactivePublicKey, isInteractive, isForceLinkInIframe, isOpenLinkInDrawer, isTextTopLayer = false, layer0, layer1, position: { x, y }, sceneDropId, text, textColor, textFontFamily, textSize, textWeight, textWidth, uniqueName, urlSlug, yOrderAdjust, }) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -43087,10 +43730,51 @@ class DroppedAssetFactory extends SDKController {
     }
 }
 
+/* ============================================================================
+  AI RULES for code assistants
+
+  - Consumers MUST create a single Topia client in their app (e.g. utils/topiaInit.ts).
+  - Consumers MUST instantiate this factory ONCE using that client and RE-USE it.
+  - Controllers/services MUST import the app’s exported factory instance.
+  - Use ONLY methods defined in this file’s types and TSDoc.
+  - Methods that DO NOT exist and MUST NOT be suggested.
+
+  RIGHT ✅ Correct usage pattern (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, Ecosystem } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const Ecosystem = new EcosystemFactory(topia);
+
+  RIGHT ✅ Correct usage pattern (controller):
+    // controllers/myController.ts
+    import { Ecosystem } from "utils/topiaInit.ts";
+    const ecosystem = await Ecosystem.create({ credentials });
+    await ecosystem.fetchDataObject();
+
+  WRONG ❌ Incorrect usage pattern (controller):
+    // controllers/myController.ts
+    import { Ecosystem, Topia } from "@rtsdk/topia";
+    const topia = new Topia(config); // ❌ new client per request
+    const Ecosystem = new EcosystemFactory(topia); // ❌ ad-hoc factory
+    const ecosystem = await Ecosystem.getById(id); // ❌ method does not exist
+
+  Do NOT instantiate factories in controllers. Do NOT invent methods.
+============================================================================ */
 /**
+ * Factory for creating Ecosystem instances. Use this factory to work with ecosystem-wide data and operations.
+ *
+ * @remarks
+ * This factory should be instantiated once per application and reused across your codebase.
+ * The Ecosystem controller provides methods to interact with data shared across multiple worlds.
+ *
+ * @keywords ecosystem, factory, create, multi-world, global, shared data, platform
+ *
  * @example
  * ```ts
- * const Ecosystem = new EcosystemFactory(myTopiaInstance);
+ * // In your initialization file (e.g., utils/topiaInit.ts)
+ * import { Topia, EcosystemFactory } from "@rtsdk/topia";
+ * const topia = new Topia({ config });
+ * export const Ecosystem = new EcosystemFactory(topia);
  * ```
  */
 class EcosystemFactory {
@@ -43098,24 +43782,86 @@ class EcosystemFactory {
         this.topia = topia;
     }
     /**
-     * Instantiate a new instance of Ecosystem class.
+     * Instantiate a new instance of Ecosystem class for interacting with ecosystem-wide data.
+     *
+     * @remarks
+     * This method creates a controller instance for accessing and managing data that spans multiple worlds.
+     * Use this for cross-world data sharing, global data objects, and ecosystem-wide operations.
+     *
+     * @keywords create, instantiate, ecosystem, initialize, global, shared data, platform
      *
      * @example
-     * ```
-     * const ecosystemInstance = await Ecosystem.create({ credentials: { interactiveNonce, interactivePublicKey, assetId, urlSlug, visitorId }});
+     * ```ts
+     * // Import the pre-initialized factory from your app's initialization file
+     * import { Ecosystem } from "utils/topiaInit.ts";
+     *
+     * // Create an Ecosystem instance with credentials
+     * const ecosystemInstance = Ecosystem.create({
+     *   credentials: {
+     *     interactiveNonce,
+     *     interactivePublicKey,
+     *     assetId,
+     *     urlSlug,
+     *     visitorId
+     *   }
+     * });
+     *
+     * // Work with ecosystem-wide data objects
+     * await ecosystemInstance.fetchDataObject("global-leaderboard");
+     * await ecosystemInstance.setDataObject("global-leaderboard", { scores: [...] });
      * ```
      *
-     * @returns {Ecosystem} Returns a new Ecosystem object.
+     * @returns {Ecosystem} Returns a new Ecosystem object for interacting with ecosystem-wide data.
      */
     create(options) {
         return new Ecosystem(this.topia, options);
     }
 }
 
+/* ============================================================================
+  AI RULES for code assistants
+
+  - Consumers MUST create a single Topia client in their app (e.g. utils/topiaInit.ts).
+  - Consumers MUST instantiate this factory ONCE using that client and RE-USE it.
+  - Controllers/services MUST import the app’s exported factory instance.
+  - Use ONLY methods defined in this file’s types and TSDoc.
+  - Methods that DO NOT exist and MUST NOT be suggested.
+
+  RIGHT ✅ Correct usage pattern (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, SceneFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const Scene = new SceneFactory(topia);
+
+  RIGHT ✅ Correct usage pattern (controller):
+    // controllers/myController.ts
+    import { Scene } from "utils/topiaInit.ts";
+    const scene = await Scene.get(sceneId, { credentials });
+
+  WRONG ❌ Incorrect usage pattern (controller):
+    // controllers/myController.ts
+    import { SceneFactory, Topia } from "@rtsdk/topia";
+    const topia = new Topia(config); // ❌ new client per request
+    const Scene = new SceneFactory(topia); // ❌ ad-hoc factory
+    const scene = await Scene.getById(sceneId);  // ❌ method does not exist
+
+  Do NOT instantiate factories in controllers. Do NOT invent methods.
+============================================================================ */
 /**
+ * Factory for creating Scene instances. Use this factory to work with scenes in the Topia platform.
+ *
+ * @remarks
+ * This factory should be instantiated once per application and reused across your codebase.
+ * Scenes represent the template or blueprint for a world's design and layout.
+ *
+ * @keywords scene, factory, create, template, blueprint, layout, design
+ *
  * @example
  * ```ts
- * const Scene = new SceneFactory(myTopiaInstance);
+ * // In your initialization file (e.g., utils/topiaInit.ts)
+ * import { Topia, SceneFactory } from "@rtsdk/topia";
+ * const topia = new Topia({ config });
+ * export const Scene = new SceneFactory(topia);
  * ```
  */
 class SceneFactory {
@@ -43124,14 +43870,38 @@ class SceneFactory {
         this.create;
     }
     /**
-     * Instantiate a new instance of Scene class.
+     * Instantiate a new instance of Scene class for an existing scene in the platform.
+     *
+     * @remarks
+     * This method creates a controller instance for working with a scene but does not fetch its properties.
+     * Use this when you need to interact with a specific scene by its ID.
+     *
+     * @keywords create, instantiate, scene, initialize, instance, template
      *
      * @example
-     * ```
-     * const sceneInstance = await Scene.create(id, { credentials: { interactiveNonce, interactivePublicKey, assetId, urlSlug, visitorId } });
+     * ```ts
+     * // Import the pre-initialized factory from your app's initialization file
+     * import { Scene } from "utils/topiaInit.ts";
+     *
+     * // Create a Scene instance with credentials
+     * const sceneInstance = Scene.create(
+     *   "scene-id-123",
+     *   {
+     *     credentials: {
+     *       interactiveNonce,
+     *       interactivePublicKey,
+     *       assetId,
+     *       urlSlug,
+     *       visitorId
+     *     }
+     *   }
+     * );
+     *
+     * // Fetch scene details if needed
+     * await sceneInstance.fetchSceneById();
      * ```
      *
-     * @returns {Scene} Returns a new Scene object.
+     * @returns {Scene} Returns a new Scene object for interacting with the specified scene.
      */
     create(id, options) {
         return new Scene(this.topia, id, options);
@@ -43155,10 +43925,51 @@ class SceneFactory {
     }
 }
 
+/* ============================================================================
+  AI RULES for code assistants
+
+  - Consumers MUST create a single Topia client in their app (e.g. utils/topiaInit.ts).
+  - Consumers MUST instantiate this factory ONCE using that client and RE-USE it.
+  - Controllers/services MUST import the app’s exported factory instance.
+  - Use ONLY methods defined in this file’s types and TSDoc.
+  - Methods that DO NOT exist and MUST NOT be suggested.
+
+  RIGHT ✅ Correct usage pattern (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, UserFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const User = new UserFactory(topia);
+
+  RIGHT ✅ Correct usage pattern (controller):
+    // controllers/myController.ts
+    import { User } from "utils/topiaInit.ts";
+    const user = await User.create({ credentials });
+    await user.fetchDataObject();
+
+  WRONG ❌ Incorrect usage pattern (controller):
+    // controllers/myController.ts
+    import { UserFactory, Topia } from "@rtsdk/topia";
+    const topia = new Topia(config); // ❌ new client per request
+    const User = new UserFactory(topia); // ❌ ad-hoc factory
+    const user = await User.getById(userId); // ❌ method does not exist
+
+  Do NOT instantiate factories in controllers. Do NOT invent methods.
+============================================================================ */
 /**
+ * Factory for creating User instances. Use this factory to work with user data in the Topia platform.
+ *
+ * @remarks
+ * This factory should be instantiated once per application and reused across your codebase.
+ * The User controller allows you to interact with user-specific information and operations.
+ *
+ * @keywords user, factory, create, account, profile, member, visitor
+ *
  * @example
  * ```ts
- * const User = new UserFactory(myTopiaInstance);
+ * // In your initialization file (e.g., utils/topiaInit.ts)
+ * import { Topia, UserFactory } from "@rtsdk/topia";
+ * const topia = new Topia({ config });
+ * export const User = new UserFactory(topia);
  * ```
  */
 class UserFactory {
@@ -43166,24 +43977,87 @@ class UserFactory {
         this.topia = topia;
     }
     /**
-     * Instantiate a new instance of User class.
+     * Instantiate a new instance of User class for working with user data.
+     *
+     * @remarks
+     * This method creates a controller instance for interacting with user-specific operations.
+     * The User controller doesn't require an ID since it represents the currently authenticated user.
+     *
+     * @keywords create, instantiate, user, initialize, account, profile, member
      *
      * @example
-     * ```
-     * const userInstance = await User.create({ credentials: { interactiveNonce, interactivePublicKey, assetId, urlSlug, visitorId } });
+     * ```ts
+     * // Import the pre-initialized factory from your app's initialization file
+     * import { User } from "utils/topiaInit.ts";
+     *
+     * // Create a User instance with credentials
+     * const userInstance = User.create({
+     *   credentials: {
+     *     interactiveNonce,
+     *     interactivePublicKey,
+     *     assetId,
+     *     urlSlug,
+     *     visitorId
+     *   }
+     * });
+     *
+     * // Use methods on the user instance
+     * await userInstance.checkInteractiveCredentials();
+     * const avatars = await userInstance.fetchAvatars();
      * ```
      *
-     * @returns {User} Returns a new User object.
+     * @returns {User} Returns a new User object for interacting with user data.
      */
     create(options) {
         return new User(this.topia, options);
     }
 }
 
+/* ============================================================================
+  AI RULES for code assistants
+
+  - Consumers MUST create a single Topia client in their app (e.g. utils/topiaInit.ts).
+  - Consumers MUST instantiate this factory ONCE using that client and RE-USE it.
+  - Controllers/services MUST import the app’s exported factory instance.
+  - Use ONLY methods defined in this file’s types and TSDoc.
+  - Methods that DO NOT exist and MUST NOT be suggested.
+
+  RIGHT ✅ Correct usage pattern (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, VisitorFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const Visitor = new VisitorFactory(topia);
+
+  RIGHT ✅ Correct usage pattern (controller):
+    // controllers/myController.ts
+    import { Visitor } from "utils/topiaInit.ts";
+    const visitor = await Visitor.get(visitorId, urlSlug, { credentials });
+    await visitor.fetchDataObject();
+
+  WRONG ❌ Incorrect usage pattern (controller):
+    // controllers/myController.ts
+    import { VisitorFactory, Topia } from "@rtsdk/topia";
+    const topia = new Topia(config); // ❌ new client per request
+    const Visitor = new VisitorFactory(topia); // ❌ ad-hoc factory
+    const visitor = await Visitor.getById(visitorId); // ❌ method does not exist
+
+  Do NOT instantiate factories in controllers. Do NOT invent methods.
+============================================================================ */
 /**
+ * Factory for creating Visitor instances. Use this factory to work with visitors in Topia worlds.
+ *
+ * @remarks
+ * This factory should be instantiated once per application and reused across your codebase.
+ * The Visitor controller represents a specific visitor/avatar instance in a world.
+ *
+ * @keywords visitor, factory, create, get, avatar, user, participant
+ *
  * @example
  * ```ts
- * const Visitor = new VisitorFactory(myTopiaInstance);
+ * // In your initialization file (e.g., utils/topiaInit.ts)
+ * import { Topia, VisitorFactory } from "@rtsdk/topia";
+ * const topia = new Topia({ config });
+ * export const Visitor = new VisitorFactory(topia);
  * ```
  */
 class VisitorFactory {
@@ -43191,27 +44065,78 @@ class VisitorFactory {
         this.topia = topia;
     }
     /**
-     * Instantiate a new instance of Visitor class.
+     * Instantiate a new instance of Visitor class for an existing visitor in a world.
+     *
+     * @remarks
+     * This method creates a controller instance for a visitor but does not fetch its properties.
+     * Use this when you need a lightweight instance and will fetch properties separately or when you already have the properties.
+     *
+     * @keywords create, instantiate, visitor, initialize, avatar, instance
      *
      * @example
-     * ```
-     * const visitorInstance = await Visitor.create(id, urlSlug, { credentials: { interactiveNonce, interactivePublicKey, assetId, urlSlug, visitorId } });
+     * ```ts
+     * // Import the pre-initialized factory from your app's initialization file
+     * import { Visitor } from "utils/topiaInit.ts";
+     *
+     * // Create a Visitor instance with credentials
+     * const visitorInstance = Visitor.create(
+     *   12345, // visitor ID
+     *   "my-world-slug",
+     *   {
+     *     credentials: {
+     *       interactiveNonce,
+     *       interactivePublicKey,
+     *       assetId,
+     *       urlSlug,
+     *       visitorId
+     *     }
+     *   }
+     * );
+     *
+     * // Later fetch visitor properties if needed
+     * await visitorInstance.fetchVisitor();
      * ```
      *
-     * @returns {Visitor} Returns a new Visitor object.
+     * @returns {Visitor} Returns a new Visitor object without fetching its properties.
      */
     create(id, urlSlug, options) {
         return new Visitor(this.topia, id, urlSlug, options);
     }
     /**
-     * Instantiate a new instance of Visitor class and retrieve all properties.
+     * Instantiate a new instance of Visitor class and automatically fetch all its properties.
+     *
+     * @remarks
+     * This method creates a controller instance and immediately fetches all properties of the visitor.
+     * It's a convenience method that combines creating an instance and calling fetchVisitor().
+     *
+     * @keywords get, fetch, retrieve, visitor, load, avatar, instance
      *
      * @example
-     * ```
-     * const visitorInstance = await Visitor.get(id, urlSlug, { credentials: { interactiveNonce, interactivePublicKey, assetId, urlSlug, visitorId } });
+     * ```ts
+     * // Import the pre-initialized factory from your app's initialization file
+     * import { Visitor } from "utils/topiaInit.ts";
+     *
+     * // Get a fully populated Visitor instance
+     * const visitorInstance = await Visitor.get(
+     *   12345, // visitor ID
+     *   "my-world-slug",
+     *   {
+     *     credentials: {
+     *       interactiveNonce,
+     *       interactivePublicKey,
+     *       assetId,
+     *       urlSlug,
+     *       visitorId
+     *     }
+     *   }
+     * );
+     *
+     * // The properties are already loaded, so you can use them immediately
+     * console.log(visitorInstance.username);
+     * console.log(visitorInstance.position);
      * ```
      *
-     * @returns {Promise<Visitor>} Returns a new Visitor object with all properties.
+     * @returns {Promise<Visitor>} Returns a new Visitor object with all properties already fetched.
      */
     get(id, urlSlug, options) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -43223,9 +44148,20 @@ class VisitorFactory {
 }
 
 /**
+ * Factory for creating WebRTCConnector instances. Use this factory to establish WebRTC connections for audio/video in Topia worlds.
+ *
+ * @remarks
+ * This factory should be instantiated once per application and reused across your codebase.
+ * The WebRTCConnector provides methods to set up and manage real-time audio/video communication.
+ *
+ * @keywords webrtc, factory, create, audio, video, communication, real-time, conference
+ *
  * @example
  * ```ts
- * const WebRTCConnector = new WebRTCConnectorFactory(myTopiaInstance);
+ * // In your initialization file (e.g., utils/topiaInit.ts)
+ * import { Topia, WebRTCConnectorFactory } from "@rtsdk/topia";
+ * const topia = new Topia({ config });
+ * export const WebRTCConnector = new WebRTCConnectorFactory(topia);
  * ```
  */
 class WebRTCConnectorFactory {
@@ -43233,24 +44169,92 @@ class WebRTCConnectorFactory {
         this.topia = topia;
     }
     /**
-     * Instantiate a new instance of WebRTCConnector class.
+     * Instantiate a new instance of WebRTCConnector class for managing audio/video communication.
+     *
+     * @remarks
+     * This method creates a controller instance for establishing and managing WebRTC connections.
+     * Use this for implementing real-time audio/video communication features in Topia worlds.
+     *
+     * @keywords create, instantiate, webrtc, initialize, audio, video, communication, stream
      *
      * @example
-     * ```
-     * const webRTCInstance = await WebRTCConnector.create({ credentials: { interactiveNonce, interactivePublicKey, assetId, urlSlug, visitorId }, twilioConfig: {} });
+     * ```ts
+     * // Import the pre-initialized factory from your app's initialization file
+     * import { WebRTCConnector } from "utils/topiaInit.ts";
+     *
+     * // Create a WebRTCConnector instance with credentials and configuration
+     * const webRTCInstance = WebRTCConnector.create(
+     *   "my-world-slug",
+     *   {
+     *     credentials: {
+     *       interactiveNonce,
+     *       interactivePublicKey,
+     *       assetId,
+     *       urlSlug,
+     *       visitorId
+     *     },
+     *     twilioConfig: {
+     *       // Twilio configuration options
+     *     }
+     *   }
+     * );
+     *
+     * // Use the instance to establish connections
+     * await webRTCInstance.connect();
      * ```
      *
-     * @returns {WebRTCConnector} Returns a new WebRTCConnector object.
+     * @returns {WebRTCConnector} Returns a new WebRTCConnector object for managing audio/video communication.
      */
     create(urlSlug, options) {
         return new WebRTCConnector(this.topia, urlSlug, options);
     }
 }
 
+/* ============================================================================
+  AI RULES for code assistants
+
+  - Consumers MUST create a single Topia client in their app (e.g. utils/topiaInit.ts).
+  - Consumers MUST instantiate this factory ONCE using that client and RE-USE it.
+  - Controllers/services MUST import the app’s exported factory instance.
+  - Use ONLY methods defined in this file’s types and TSDoc.
+  - Methods that DO NOT exist and MUST NOT be suggested.
+
+  RIGHT ✅ Correct usage pattern (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, WorldActivityFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const WorldActivity = new WorldActivityFactory(topia);
+
+  RIGHT ✅ Correct usage pattern (controller):
+    // controllers/myController.ts
+    import { WorldActivity } from "utils/topiaInit.ts";
+    const activity = await WorldActivity.create(urlSlug, { credentials });
+    await activity.currentVisitors();
+
+  WRONG ❌ Incorrect usage pattern (controller):
+    // controllers/myController.ts
+    import { WorldActivity, Topia } from "@rtsdk/topia";
+    const topia = new Topia(config); // ❌ new client per request
+    const WorldActivity = new WorldActivityFactory(topia); // ❌ ad-hoc factory
+    const activity = await WorldActivity.getAllVisitors(); // ❌ method does not exist
+
+  Do NOT instantiate factories in controllers. Do NOT invent methods.
+============================================================================ */
 /**
+ * Factory for creating WorldActivity instances. Use this factory to monitor and manage visitor activity in Topia worlds.
+ *
+ * @remarks
+ * This factory should be instantiated once per application and reused across your codebase.
+ * The WorldActivity controller provides methods to interact with real-time visitor activities and movements.
+ *
+ * @keywords world activity, factory, create, visitors, movement, tracking, presence, real-time
+ *
  * @example
  * ```ts
- * const WorldActivity = new WorldActivityFactory(myTopiaInstance);
+ * // In your initialization file (e.g., utils/topiaInit.ts)
+ * import { Topia, WorldActivityFactory } from "@rtsdk/topia";
+ * const topia = new Topia({ config });
+ * export const WorldActivity = new WorldActivityFactory(topia);
  * ```
  */
 class WorldActivityFactory {
@@ -43258,24 +44262,93 @@ class WorldActivityFactory {
         this.topia = topia;
     }
     /**
-     * Instantiate a new instance of WorldActivity class.
+     * Instantiate a new instance of WorldActivity class for monitoring visitor activity in a specific world.
+     *
+     * @remarks
+     * This method creates a controller instance for tracking and managing visitor activity in a world.
+     * Use this to fetch current visitors, move visitors, or monitor specific zones within a world.
+     *
+     * @keywords create, instantiate, world activity, initialize, visitors, tracking, presence
      *
      * @example
-     * ```
-     * const worldActivityInstance = await WorldActivity.create(urlSlug, { credentials: { interactiveNonce, interactivePublicKey, assetId, urlSlug, visitorId } });
+     * ```ts
+     * // Import the pre-initialized factory from your app's initialization file
+     * import { WorldActivity } from "utils/topiaInit.ts";
+     *
+     * // Create a WorldActivity instance with credentials
+     * const worldActivityInstance = WorldActivity.create(
+     *   "my-world-slug",
+     *   {
+     *     credentials: {
+     *       interactiveNonce,
+     *       interactivePublicKey,
+     *       assetId,
+     *       urlSlug,
+     *       visitorId
+     *     }
+     *   }
+     * );
+     *
+     * // Get current visitors in the world
+     * const visitors = await worldActivityInstance.currentVisitors();
+     * console.log(`There are ${visitors.length} visitors in the world`);
+     *
+     * // Check visitors in a specific zone
+     * const zoneVisitors = await worldActivityInstance.fetchVisitorsInZone("stage-area");
      * ```
      *
-     * @returns {WorldActivity} Returns a new WorldActivity object.
+     * @returns {WorldActivity} Returns a new WorldActivity object for tracking and managing visitor activity.
      */
     create(urlSlug, options) {
         return new WorldActivity(this.topia, urlSlug, options);
     }
 }
 
+/* ============================================================================
+  AI RULES for code assistants
+
+  - Consumers MUST create a single Topia client in their app (e.g. utils/topiaInit.ts).
+  - Consumers MUST instantiate this factory ONCE using that client and RE-USE it.
+  - Controllers/services MUST import the app’s exported factory instance.
+  - Use ONLY methods defined in this file’s types and TSDoc.
+  - Methods that DO NOT exist and MUST NOT be suggested.
+
+  RIGHT ✅ Correct usage pattern (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, WorldFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const World = new WorldFactory(topia);
+
+  RIGHT ✅ Correct usage pattern (controller):
+    // controllers/myController.ts
+    import { World } from "utils/topiaInit.ts";
+    const world = await World.create(urlSlug, { credentials });
+    await world.fetchDetails();
+
+  WRONG ❌ Incorrect usage pattern (controller):
+    // controllers/myController.ts
+    import { World, Topia } from "@rtsdk/topia";
+    const topia = new Topia(config); // ❌ new client per request
+    const World = new WorldFactory(topia); // ❌ ad-hoc factory
+    const world = await World.update({}); // ❌ method does not exist
+
+  Do NOT instantiate factories in controllers. Do NOT invent methods.
+============================================================================ */
 /**
+ * Factory for creating World instances. Use this factory to interact with Topia worlds.
+ *
+ * @remarks
+ * This factory should be instantiated once per application and reused across your codebase.
+ * The World controller provides methods to manage world settings, retrieve world details, and perform world-level operations.
+ *
+ * @keywords world, factory, create, virtual space, environment, room, topia
+ *
  * @example
  * ```ts
- * const World = new WorldFactory(myTopiaInstance);
+ * // In your initialization file (e.g., utils/topiaInit.ts)
+ * import { Topia, WorldFactory } from "@rtsdk/topia";
+ * const topia = new Topia({ config });
+ * export const World = new WorldFactory(topia);
  * ```
  */
 class WorldFactory extends SDKController {
@@ -43283,27 +44356,75 @@ class WorldFactory extends SDKController {
         super(topia);
     }
     /**
-     * Instantiate a new instance of World class.
+     * Instantiate a new instance of World class for interacting with a specific Topia world.
+     *
+     * @remarks
+     * This method creates a controller instance for a world identified by its URL slug.
+     * The world controller can be used to fetch details, update world settings, and perform other world-level operations.
+     *
+     * @keywords create, instantiate, world, initialize, virtual space, environment, room
      *
      * @example
-     * ```
-     * const worldInstance = await World.create(urlSlug, { credentials: { interactiveNonce, interactivePublicKey, assetId, urlSlug, visitorId } });
+     * ```ts
+     * // Import the pre-initialized factory from your app's initialization file
+     * import { World } from "utils/topiaInit.ts";
+     *
+     * // Create a World instance with credentials
+     * const worldInstance = World.create(
+     *   "my-world-slug",
+     *   {
+     *     credentials: {
+     *       interactiveNonce,
+     *       interactivePublicKey,
+     *       assetId,
+     *       urlSlug,
+     *       visitorId
+     *     }
+     *   }
+     * );
+     *
+     * // Fetch world details
+     * await worldInstance.fetchDetails();
+     * console.log(worldInstance.name);
      * ```
      *
-     * @returns {World} Returns a new World object.
+     * @returns {World} Returns a new World object for interacting with the specified world.
      */
     create(urlSlug, options) {
         return new World(this.topia, urlSlug, options);
     }
     /**
-     * Deletes an array of Dropped Assets from within a world and returns success: true
+     * Deletes multiple dropped assets from a world in a single operation.
+     *
+     * @remarks
+     * This method provides a convenient way to delete multiple dropped assets at once rather than
+     * deleting them one by one. Requires appropriate permissions via interactive credentials.
+     *
+     * @keywords delete, remove, dropped assets, multiple, batch, cleanup, world
      *
      * @example
-     * ```
-     * await World.deleteDroppedAssets(urlSlug, ["exampleDroppedAssetId1", "exampleDroppedAssetId2"], interactiveSecret, credentials);
+     * ```ts
+     * // Import the pre-initialized factory from your app's initialization file
+     * import { World } from "utils/topiaInit.ts";
+     *
+     * // Delete multiple dropped assets from a world
+     * const result = await World.deleteDroppedAssets(
+     *   "my-world-slug",
+     *   ["asset-id-123", "asset-id-456", "asset-id-789"],
+     *   "your-interactive-secret",
+     *   {
+     *     apiKey: "your-api-key",
+     *     interactivePublicKey: "your-public-key",
+     *     visitorId: 12345
+     *   }
+     * );
+     *
+     * if (result.success) {
+     *   console.log("Assets successfully deleted");
+     * }
      * ```
      *
-     * @returns {Promise<{ success: boolean }>} Returns `{ success: true }` or an error.
+     * @returns {Promise<{ success: boolean }>} Returns `{ success: true }` if all assets were deleted successfully.
      */
     deleteDroppedAssets(urlSlug, droppedAssetIds, interactiveSecret, credentials) {
         return __awaiter(this, void 0, void 0, function* () {