docs: add and unify README documentation across all packages

Summary:
add and unify README documentation across all packages

includes some formatting fixes with pnpm run format

Reviewed By: zjm-meta

Differential Revision: D89694178

fbshipit-source-id: 82a2835dad6f0d0766d019fd1310eb7962b351b0

Author: felixtrz

README.md

@@ -13,46 +13,82 @@ The **Immersive Web SDK** makes building immersive web experiences as approachab
 
 **Same code, two experiences**: Run immersively in VR/AR headsets and automatically provide mouse-and-keyboard emulation on desktop browsers. No browser extensions, no special setup—anyone with a laptop can develop for the immersive web.
 
-## Quick Start
+## Getting Started
+
+Create a new project with a single command:
 
 ```bash
-# Install dependencies
-pnpm install
+npm create @iwsdk@latest
+```
 
-# Build and pack all packages
-pnpm run build:tgz
+Or install into an existing project:
 
-# Run example
-cd examples/locomotion && pnpm run fresh:dev
+```bash
+npm install @iwsdk/core three
 ```
 
+## Documentation
+
+For guides, concepts, and API reference, visit: **[https://iwsdk.dev](https://iwsdk.dev)**
+
+## Packages
+
+| Package                                                                    | Description                                       |
+| -------------------------------------------------------------------------- | ------------------------------------------------- |
+| [@iwsdk/core](./packages/core)                                             | Core SDK with ECS, systems, and WebXR integration |
+| [@iwsdk/create](./packages/create)                                         | CLI for scaffolding new projects                  |
+| [@iwsdk/glxf](./packages/glxf)                                             | GLXF scene format loader for Three.js             |
+| [@iwsdk/locomotor](./packages/locomotor)                                   | Locomotion engine for Three.js WebXR              |
+| [@iwsdk/xr-input](./packages/xr-input)                                     | WebXR input system for Three.js                   |
+| [@iwsdk/vite-plugin-iwer](./packages/vite-plugin-iwer)                     | WebXR emulator injection for development          |
+| [@iwsdk/vite-plugin-gltf-optimizer](./packages/vite-plugin-gltf-optimizer) | GLTF/GLB optimization during build                |
+| [@iwsdk/vite-plugin-uikitml](./packages/vite-plugin-uikitml)               | UIKitML to JSON compiler for spatial UI           |
+| [@iwsdk/vite-plugin-metaspatial](./packages/vite-plugin-metaspatial)       | Meta Spatial Editor integration                   |
+
+### Internal Packages
+
+| Package                                            | Description                             |
+| -------------------------------------------------- | --------------------------------------- |
+| [@iwsdk/starter-assets](./packages/starter-assets) | CDN-hosted templates and assets for CLI |
+
 ## Development
 
 ```bash
-# Lint and format code
+# Install dependencies
+pnpm install
+
+# Build all packages as tgz files (for examples to consume)
+npm run build:tgz
+
+# Run an example (fresh install from local tgz packages)
+cd examples/locomotion && npm run fresh:dev
+
+# Lint and format
 pnpm run lint
 pnpm run format
 
-# Build specific package
-pnpm --filter '@iwsdk/core' run build
+# Build a specific package
+pnpm --filter @iwsdk/core build
 ```
 
-## Documentation
+### Development Workflow
 
-For detailed information about using IWSDK, including step-by-step guides, architectural concepts, and complete API references, please visit our documentation site:
+The examples use `file:` dependencies pointing to `.tgz` files built from local packages. This simulates how end-users will consume the packages from npm.
 
-- **[IWSDK Documentation](https://facebook.github.io/immersive-web-sdk)**
+1. **`npm run build:tgz`** - Builds all packages in dependency order and creates `.tgz` archives
+2. **`npm run fresh:dev`** (in example) - Cleans `node_modules`, reinstalls from tgz files, and starts dev server
+
+This ensures examples always test against the latest local build.
 
 ## License
 
-IWSDK is licensed under the MIT License. For more details, see the [LICENSE](https://github.com/facebook/immersive-web-sdk/blob/main/LICENSE) file in this repository.
+IWSDK is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.
 
 ## Contributing
 
-Your contributions are welcome! Please feel free to submit issues and pull requests. Before contributing, make sure to review our [Contributing Guidelines](https://github.com/facebook/immersive-web-sdk/blob/main/CONTRIBUTING.md) and [Code of Conduct](https://github.com/facebook/immersive-web-sdk/blob/main/CODE_OF_CONDUCT.md).
+Contributions are welcome! Please review our [Contributing Guidelines](./CONTRIBUTING.md) and [Code of Conduct](./CODE_OF_CONDUCT.md) before submitting issues or pull requests.
 
 ## Developer Terms
 
-- Open source Terms of Use - https://opensource.fb.com/legal/terms
-
-- Open source Privacy Policy - https://opensource.fb.com/legal/privacy
+- [Open Source Terms of Use](https://opensource.fb.com/legal/terms)
+- [Open Source Privacy Policy](https://opensource.fb.com/legal/privacy)

examples/physics/README.md

@@ -89,9 +89,9 @@ Enable physics in your world configuration:
 ```javascript
 World.create(document.getElementById('scene-container'), {
   features: {
-    physics: true,  // Enable Havok physics engine
-    grabbing: true,  // Enable object grabbing
-    locomotion: true,  // Enable player movement
+    physics: true, // Enable Havok physics engine
+    grabbing: true, // Enable object grabbing
+    locomotion: true, // Enable player movement
   },
 });
 ```
@@ -105,18 +105,21 @@ The physics system uses three main ECS components:
 Defines the motion type and physical behavior of an entity. See `immersive-web-sdk/packages/core/src/physics/physicsBody.ts:47-66`
 
 **Motion Types** (`PhysicsState`):
+
 - **`Static`**: Immovable objects like walls and floors. Affects other bodies but never moves.
 - **`Dynamic`**: Objects that respond to forces, collisions, and gravity.
 - **`Kinematic`**: Programmatically controlled objects that push dynamic bodies but aren't affected by physics.
 
 **Properties**:
+
 - `state`: Motion type (default: `PhysicsState.Dynamic`)
 - `linearDamping`: Reduces linear velocity over time (default: 0.0)
 - `angularDamping`: Reduces angular velocity over time (default: 0.0)
 - `gravityFactor`: Multiplier for gravity effect (default: 1.0)
 - `centerOfMass`: Custom center of mass offset (default: auto-calculated)
 
 **Example**:
+
 ```javascript
 entity.addComponent(PhysicsBody, {
   state: PhysicsState.Dynamic,
@@ -130,6 +133,7 @@ entity.addComponent(PhysicsBody, {
 Defines the collision shape and material properties. See `immersive-web-sdk/packages/core/src/physics/physicsShape.ts:80-100`
 
 **Shape Types** (`PhysicsShapeType`):
+
 - **`Sphere`**: Defined by radius in `dimensions[0]`. Efficient for round objects.
 - **`Box`**: Defined by `[width, height, depth]` in dimensions. Good for rectangular objects.
 - **`Cylinder`**: Defined by radius in `dimensions[0]` and height in `dimensions[1]`.
@@ -138,18 +142,20 @@ Defines the collision shape and material properties. See `immersive-web-sdk/pack
 - **`Auto`**: Automatically detects the best shape from Three.js geometry (SphereGeometry → Sphere, BoxGeometry → Box, etc.)
 
 **Material Properties**:
+
 - `density`: Mass per unit volume (default: 1.0)
 - `restitution`: Bounciness, 0 = no bounce, 1 = perfect bounce (default: 0.0)
 - `friction`: Surface friction (default: 0.5)
 
 **Example**:
+
 ```javascript
 entity.addComponent(PhysicsShape, {
   shape: PhysicsShapeType.Sphere,
-  dimensions: [0.5, 0, 0],  // radius = 0.5 meters
+  dimensions: [0.5, 0, 0], // radius = 0.5 meters
   density: 2.0,
-  restitution: 0.8,  // bouncy
-  friction: 0.1,     // slippery
+  restitution: 0.8, // bouncy
+  friction: 0.1, // slippery
 });
 ```
 
@@ -158,15 +164,17 @@ entity.addComponent(PhysicsShape, {
 Applies one-time forces or velocity changes to a physics body. The component is automatically removed after application. See `immersive-web-sdk/packages/core/src/physics/physicsManipulation.ts:37-48`
 
 **Properties**:
+
 - `force`: Impulse force vector `[x, y, z]`
 - `linearVelocity`: Set linear velocity directly `[x, y, z]`
 - `angularVelocity`: Set angular velocity directly `[x, y, z]`
 
 **Example**:
+
 ```javascript
 // Apply an impulse force
 entity.addComponent(PhysicsManipulation, {
-  force: [10, 5, 0],  // Push right and up
+  force: [10, 5, 0], // Push right and up
 });
 ```
 
@@ -193,10 +201,10 @@ entity.addComponent(PhysicsShape, {
   dimensions: [0.2],
 });
 entity.addComponent(PhysicsBody, {
-  state: PhysicsState.Dynamic
+  state: PhysicsState.Dynamic,
 });
 entity.addComponent(PhysicsManipulation, {
-  force: [10, 1, 1]
+  force: [10, 1, 1],
 });
 ```
 

examples/scene-understanding/README.md

@@ -80,14 +80,14 @@ World.create(document.getElementById('scene-container'), {
     sessionMode: SessionMode.ImmersiveAR,
     features: {
       hitTest: true,
-      planeDetection: { required: true },    // Enable plane detection
-      meshDetection: { required: true },     // Enable mesh detection
-      anchors: { required: true },           // Enable spatial anchors
+      planeDetection: { required: true }, // Enable plane detection
+      meshDetection: { required: true }, // Enable mesh detection
+      anchors: { required: true }, // Enable spatial anchors
     },
   },
   features: {
     grabbing: true,
-    sceneUnderstanding: true,  // Enable IWSDK scene understanding system
+    sceneUnderstanding: true, // Enable IWSDK scene understanding system
   },
 });
 ```
@@ -107,6 +107,7 @@ Planes are automatically created and updated by the `SceneUnderstandingSystem` a
 Represents detected 3D geometry in the environment. See `immersive-web-sdk/packages/core/src/scene-understanding/mesh.ts:43-55`
 
 **Properties**:
+
 - `isBounded3D`: Whether this is a bounded object (true) or global mesh (false)
 - `semanticLabel`: Semantic label from the device (e.g., "wall", "couch", "global mesh")
 - `min`: Minimum bounding box corner `[x, y, z]`
@@ -120,9 +121,11 @@ Meshes are automatically created and updated by the `SceneUnderstandingSystem` h
 Marks an entity to be anchored at a fixed position in the real world (will not move after recentering the view). See `immersive-web-sdk/packages/core/src/scene-understanding/anchor.ts:35-45`
 
 **Properties**:
+
 - `attached`: Boolean indicating if the entity is attached to the anchor group, default `false`
 
 **Usage**:
+
 ```javascript
 // Create an entity that stays fixed in the real world
 const entity = world.createTransformEntity(mesh);
@@ -131,7 +134,6 @@ entity.addComponent(XRAnchor);
 
 Objects with the `XRAnchor` component are automatically attached to a stable anchor point by the `SceneUnderstandingSystem`.
 
-
 ### How Scene Understanding Works
 
 The `SceneUnderstandingSystem` (see `src/scene-understanding/scene-understanding-system.ts:72-408`) handles:
@@ -152,16 +154,19 @@ Scene understanding features require specific hardware capabilities. Always chec
 ### Working with Meshes
 
 **Mesh Types**:
+
 - **Bounded meshes** (`isBounded3D: true`): Individual objects like furniture, walls
 - **Global mesh** (`isBounded3D: false`): Environment-wide mesh without semantic meaning
 
 **Best Practices**:
+
 - Use `semanticLabel` to identify what the mesh represents (e.g., "couch", "wall", "table")
 - Bounded meshes include useful bounding box data (`min`, `max`, `dimensions`)
 - Global meshes are useful for physics or collision but not for semantic understanding
 - Filter by `isBounded3D` to work with specific objects vs. the entire environment
 
 **Example: Finding Furniture**:
+
 ```javascript
 this.queries.meshEntities.entities.forEach((meshEntity) => {
   const label = meshEntity.getValue(XRMesh, 'semanticLabel');
@@ -178,15 +183,18 @@ this.queries.meshEntities.entities.forEach((meshEntity) => {
 ### Working with Anchors
 
 **Anchor Behavior**:
+
 - Anchors keep objects fixed in the real world even as the device tracking shifts
 - Perfect for persistent AR content that should stay in one place
 - The system maintains anchor stability by updating transforms automatically
 
 **Tips**:
+
 - Use anchors for important objects that must stay in a specific location
 - Can be combine with `DistanceGrabbable` to let users position objects precisely
 
 **Example: User-Placed Anchored Object**:
+
 ```javascript
 // Let user grab and position an anchored object
 const entity = world.createTransformEntity(mesh);
@@ -216,11 +224,13 @@ WebXR requires HTTPS for all features to work properly. This example includes:
 **For Meta Quest Devices**:
 
 1. Start the dev server:
+
 ```bash
 pnpm dev
 ```
 
 2. On your Quest device, open the browser and navigate to:
+
 ```
 https://YOUR_LOCAL_IP:8081
 ```
@@ -233,7 +243,6 @@ https://YOUR_LOCAL_IP:8081
 
 ## 🛠 Customization
 
-
 ### Enabling Wireframe Toggle
 
 The `SceneUnderstandingSystem` has a built-in `showWireFrame` config option:
@@ -244,13 +253,13 @@ World.create(document.getElementById('scene-container'), {
     sessionMode: SessionMode.ImmersiveAR,
     features: {
       hitTest: true,
-      planeDetection: { required: true },    // Enable plane detection
-      meshDetection: { required: true },     // Enable mesh detection
-      anchors: { required: true },           // Enable spatial anchors
+      planeDetection: { required: true }, // Enable plane detection
+      meshDetection: { required: true }, // Enable mesh detection
+      anchors: { required: true }, // Enable spatial anchors
     },
   },
   features: {
-    sceneUnderstanding: { showWireFrame: true },  // Enable IWSDK scene understanding system with wireframe enabled
+    sceneUnderstanding: { showWireFrame: true }, // Enable IWSDK scene understanding system with wireframe enabled
   },
 });
 ```
@@ -278,18 +287,21 @@ This example demonstrates integration with:
 ### Use Cases for Scene Understanding
 
 **Plane Detection**:
+
 - Furniture placement apps
 - AR games that need floor/table surfaces
 - Virtual interior design
 - Educational AR overlays on walls
 
 **Mesh Detection**:
+
 - Obstacle avoidance for AR navigation
 - Environment-aware lighting and shadows
 - Physics interactions with real objects
 - Semantic understanding for context-aware apps
 
 **Spatial Anchors**:
+
 - Persistent AR content that stays in place
 - Multi-user AR experiences with shared reference points
 - AR annotations on real-world objects