@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/realitykit-ar/SKILL.md

@@ -1,500 +1,308 @@
 ---
 name: realitykit-ar
-description: "Build iOS augmented reality and 3D experiences with RealityKit and ARKit. Use when adding RealityView content, loading entities or USDZ models, anchoring objects to planes or world positions, distinguishing entity hit tests from ARKit real-world raycasts, handling AR camera availability, world tracking, scene updates, or RealityKit entity gestures and interactions."
+description: "RealityKit and ARKit on iOS: RealityView camera content, AR camera availability and permission, entities and components, USDZ loading, plane and world anchoring, entity hit tests versus ARKit raycasts, entity gestures, per-frame scene updates, world tracking, physics, materials, performance. Use when building iOS AR or 3D experiences."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
-# RealityKit
-Build AR experiences on iOS using RealityKit for rendering and ARKit for world
-tracking. Covers `RealityView`, entity management, raycasting, scene
-understanding, and gesture-based interactions. Targets Swift 6.3 / iOS 26+.
-
-## Contents
-
-- [Setup](#setup)
-- [RealityView Basics](#realityview-basics)
-- [Loading and Creating Entities](#loading-and-creating-entities)
-- [Anchoring and Placement](#anchoring-and-placement)
-- [Raycasting](#raycasting)
-- [Gestures and Interaction](#gestures-and-interaction)
-- [Scene Understanding](#scene-understanding)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
 
-## Setup
+# RealityKit and ARKit on iOS
 
-### Project Configuration
+RealityKit draws the 3D content; ARKit tracks the device in the room. Code here
+targets Swift 6.3 and iOS 26 or later.
 
-1. Add `NSCameraUsageDescription` to Info.plist
-2. On iOS, `RealityViewCameraContent` displays an AR camera view by default (iOS 18+, macOS 15+); use `.virtual` camera mode for explicit non-AR fallback
-3. No entitlement is required for basic AR. If AR is core to the app, add the `arkit` required-device capability; otherwise gate AR UI with `isSupported`.
+## Setup
 
-### Device Requirements
+### Project configuration
 
-AR features require devices with an A9 chip or later. Always check
-`ARWorldTrackingConfiguration.isSupported` before presenting AR UI.
+- Info.plist needs `NSCameraUsageDescription`.
+- On iOS, `RealityViewCameraContent` (iOS 18+, macOS 15+) shows the AR camera
+  feed by default. Switch to the `.virtual` camera when you want a plain 3D
+  view without AR.
+- Basic AR needs no entitlement.
+- If the app is useless without AR, list `arkit` under
+  `UIRequiredDeviceCapabilities`. Otherwise keep the app installable everywhere
+  and hide AR features at runtime with `isSupported`.
 
-```swift
-import ARKit
+### Device support
 
-guard ARWorldTrackingConfiguration.isSupported else {
-    showUnsupportedDeviceMessage()
-    return
-}
-```
+World tracking needs an A9 chip or newer. Check
+`ARWorldTrackingConfiguration.isSupported` every time before presenting AR UI.
 
-### Key Types
+### Main types
 
-| Type | Platform | Role |
-|---|---|---|
-| `RealityView` | iOS 18+, visionOS 1+ | SwiftUI view that hosts RealityKit content |
-| `RealityViewCameraContent` | iOS 18+, macOS 15+ | Content displayed through an AR camera view on iOS, non-AR on macOS |
-| `Entity` | All | Base class for all scene objects |
-| `ModelEntity` | All | Entity with a visible 3D model |
-| `AnchorEntity` | All | Tethers entities to a real-world anchor |
+| Type | Availability | Role |
+| --- | --- | --- |
+| `RealityView` | iOS 18+, visionOS 1+ | Embeds a RealityKit scene in SwiftUI |
+| `RealityViewCameraContent` | iOS 18+, macOS 15+ | Camera-backed content: AR on iOS, plain 3D on macOS |
+| `Entity` | | Base class for everything in a scene |
+| `ModelEntity` | | Entity that renders a mesh |
+| `AnchorEntity` | | Ties children to something in the real world |
 
-## RealityView Basics
-
-`RealityView` is the SwiftUI entry point for RealityKit.
-`RealityViewCameraContent` is the iOS/macOS content type. On iOS, it uses an AR
-camera view by default and can use `content.camera = .virtual` for non-AR mode
-when requested or when AR/camera access is unavailable.
+## RealityView basics
 
 ```swift
 import ARKit
-import SwiftUI
 import RealityKit
+import SwiftUI
 
-struct ARExperienceView: View {
+struct MarbleView: View {
     var body: some View {
-        RealityView { (content: RealityViewCameraContent) in
-            if !ARWorldTrackingConfiguration.isSupported {
-                content.camera = .virtual
-            }
-
-            let sphere = ModelEntity(
-                mesh: .generateSphere(radius: 0.05),
-                materials: [SimpleMaterial(
-                    color: .blue,
-                    isMetallic: true
-                )]
+        RealityView { (scene: inout RealityViewCameraContent) in
+            let tracks = ARWorldTrackingConfiguration.isSupported
+            if tracks == false { scene.camera = .virtual }
+            let marble = ModelEntity(
+                mesh: .generateSphere(radius: 0.04),
+                materials: [SimpleMaterial(color: .systemTeal, isMetallic: true)]
             )
-            sphere.position = [0, 0, -0.5]  // 50cm in front of camera
-            content.add(sphere)
+            marble.position = SIMD3(x: 0, y: 0, z: -0.5)
+            scene.add(marble)
         }
     }
 }
 ```
 
-### Make and Update Pattern
+Distances are in meters, so `-0.5` on z puts the marble half a meter in front
+of the camera. Use `.virtual` whenever the user asks for a non-AR view, or when
+world tracking or the camera is unavailable.
 
-Use the `update` closure to respond to SwiftUI state changes:
+### Make, then update
+
+The first closure builds the scene once. The `update:` closure runs when SwiftUI
+state it reads changes, so it only adjusts what already exists.
 
 ```swift
-struct PlacementView: View {
-    @State private var modelColor: UIColor = .red
+struct TintedMarble: View {
+    var tint: UIColor
 
     var body: some View {
-        RealityView { content in
-            let box = ModelEntity(
-                mesh: .generateBox(size: 0.1),
-                materials: [SimpleMaterial(
-                    color: .red,
-                    isMetallic: false
-                )]
-            )
-            box.name = "colorBox"
-            box.position = [0, 0, -0.5]
-            content.add(box)
-        } update: { content in
-            if let box = content.entities.first(
-                where: { $0.name == "colorBox" }
-            ) as? ModelEntity {
-                box.model?.materials = [SimpleMaterial(
-                    color: modelColor,
-                    isMetallic: false
-                )]
-            }
-        }
-
-        Button("Change Color") {
-            modelColor = modelColor == .red ? .green : .red
+        RealityView { scene in
+            let marble = ModelEntity(mesh: .generateSphere(radius: 0.04))
+            marble.name = "marble"
+            scene.add(marble)
+        } update: { scene in
+            let marble = scene.entities.first { $0.name == "marble" } as? ModelEntity
+            marble?.model?.materials = [SimpleMaterial(color: tint, isMetallic: false)]
         }
     }
 }
 ```
 
-## Loading and Creating Entities
+## Loading and composing entities
 
-### Loading from USDZ Files
-
-Load 3D models asynchronously to avoid blocking the main thread:
+Load USDZ files asynchronously inside the make closure, which is already
+`async`:
 
 ```swift
 RealityView { content in
-    if let robot = try? await ModelEntity(named: "robot") {
-        robot.position = [0, -0.2, -0.8]
-        robot.scale = [0.01, 0.01, 0.01]
-        content.add(robot)
-    }
+    guard let lamp = try? await ModelEntity(named: "desk_lamp") else { return }
+    lamp.scale = SIMD3(repeating: 0.01)
+    lamp.position = SIMD3(x: 0, y: -0.2, z: -0.8)
+    content.add(lamp)
 }
 ```
 
-### Adding Components
-
-Entities use an ECS (Entity Component System) architecture. Add components
-to give entities behavior:
+Behaviour comes from components (entity component system), attached with
+`entity.components.set(...)`:
 
 ```swift
-let box = ModelEntity(
-    mesh: .generateBox(size: 0.1),
-    materials: [SimpleMaterial(color: .red, isMetallic: false)]
-)
-
-// Make it respond to physics
-box.components.set(PhysicsBodyComponent(
-    massProperties: .default,
-    material: .default,
-    mode: .dynamic
-))
-
-// Add collision shape for interaction
-box.components.set(CollisionComponent(
-    shapes: [.generateBox(size: [0.1, 0.1, 0.1])]
-))
-
-// Enable input targeting for gestures
-box.components.set(InputTargetComponent())
+@MainActor
+func makeThrowable(_ crate: ModelEntity) {
+    let body = PhysicsBodyComponent(massProperties: .default, material: .default, mode: .dynamic)
+    let shape = CollisionComponent(shapes: [.generateBox(size: SIMD3(repeating: 0.1))])
+    crate.components.set([body, shape, InputTargetComponent()])
+}
 ```
 
-## Anchoring and Placement
-
-### AnchorEntity
+- `PhysicsBodyComponent` puts the entity in the physics simulation.
+- `CollisionComponent` gives it a shape for collisions and for picking.
+- `InputTargetComponent` lets gestures target it.
 
-Use `AnchorEntity` to anchor content to detected surfaces or world positions:
+## Anchoring and placement
 
 ```swift
 RealityView { content in
-    // Anchor to a horizontal surface
-    let floorAnchor = AnchorEntity(.plane(
-        .horizontal,
-        classification: .floor,
-        minimumBounds: [0.2, 0.2]
-    ))
-
-    let model = ModelEntity(
-        mesh: .generateBox(size: 0.1),
-        materials: [SimpleMaterial(color: .orange, isMetallic: false)]
-    )
-    floorAnchor.addChild(model)
-    content.add(floorAnchor)
+    let floorSpot = SIMD2<Float>(0.2, 0.2)
+    let rug = AnchorEntity(.plane(.horizontal, classification: .floor, minimumBounds: floorSpot))
+    rug.addChild(ModelEntity(mesh: .generatePlane(width: 0.5, depth: 0.3)))
+    content.add(rug)
 }
 ```
 
-### Anchor Targets
-
-| Target | Description |
-|---|---|
-| `.plane(.horizontal, ...)` | Horizontal surfaces (floors, tables) |
-| `.plane(.vertical, ...)` | Vertical surfaces (walls) |
-| `.plane(.any, ...)` | Any detected plane |
-| `.world(transform:)` | Fixed world-space position |
+| Target | Use for |
+| --- | --- |
+| `.plane(.horizontal, ...)` | Floors, tables |
+| `.plane(.vertical, ...)` | Walls |
+| `.plane(.any, ...)` | Whatever plane is found first |
+| `.world(transform:)` | A fixed position in world space |
 
-## Raycasting
+## Raycasting: three different questions
 
-Keep RealityKit scene queries separate from ARKit real-world raycasts:
+Scene queries and real-world raycasts answer different questions. Keep them
+apart.
 
-- `RealityViewCameraContent.ray(through:in:to:)` returns a camera ray in
-  RealityKit coordinate spaces. It projects a screen point into the virtual
-  scene; it is not proof of a detected physical surface.
-- `RealityViewCameraContent.hitTest(point:in:query:mask:)` hits virtual
-  entities made hittable by `CollisionComponent` shapes. Use those shapes for
-  entity picking and targeted gestures, not ARKit plane detection.
-- Use `AnchorEntity(.plane(...))` for simple placement on detected planes.
-- Use ARKit `ARRaycastQuery` plus `ARSession.raycast(_:)` when the task needs
-  a one-shot intersection with real-world surfaces, then anchor with
-  `AnchorEntity(raycastResult:)`.
+- `RealityViewCameraContent.ray(through:in:to:)` turns a screen point into a
+  ray in RealityKit coordinates. It points into the virtual scene and proves
+  nothing about real-world geometry.
+- The content's `hitTest(point:in:query:mask:)` method finds virtual
+  entities that carry `CollisionComponent` shapes. Use it to pick entities and
+  target gestures, never to find planes.
+- For simple placement on a detected plane, use `AnchorEntity(.plane(...))`.
+- To intersect a real surface once, build an ARKit `ARRaycastQuery`, run it
+  with `ARSession.raycast(_:)`, and anchor with `AnchorEntity(raycastResult:)`.
 
 ```swift
-let results = session.raycast(query)
-if let result = results.first {
-    let anchor = AnchorEntity(raycastResult: result)
-    anchor.addChild(model)
+@MainActor
+func placeOnSurface(_ item: Entity, query: ARRaycastQuery, session: ARSession, into content: RealityViewCameraContent) {
+    guard let hit = session.raycast(query).first else { return }
+    let anchor = AnchorEntity(raycastResult: hit)
+    anchor.addChild(item)
     content.add(anchor)
 }
 ```
 
-Do not treat entity hit tests as substitutes for ARKit surface raycasts.
+An entity hit test is never a stand-in for an ARKit surface raycast.
 
-## Gestures and Interaction
+## Gestures and interaction
 
-For gesture-based entity interaction, add `CollisionComponent` for the hittable
-shape and `InputTargetComponent` for input targeting. Use
-`AccessibilityComponent` for entity labels/actions. Hand detailed SwiftUI gesture
-composition and VoiceOver/Switch Control policy to sibling skills.
+Entity gestures need two components: `CollisionComponent` so there is a shape
+to hit, and `InputTargetComponent` so input is routed to it. Collision shapes
+make an entity hittable by `hitTest`, `SpatialTapGesture` and
+`targetedToAnyEntity()`; this is virtual picking, not surface detection.
+`AccessibilityComponent` carries an entity's label and actions. How SwiftUI gestures
+combine, and the policy for VoiceOver or Switch Control, belong to the gesture
+and accessibility skills.
 
-### Drag Gesture on Entities
+The iOS SDK has neither `location3D` on a drag value nor
+`convert(_:from:to:)` on the targeted value; those are visionOS API. Map the 2D location into the parent
+entity's space with `unproject(_:to:)` (iOS 18+), which returns `nil` when the
+point cannot be mapped.
 
 ```swift
-struct DraggableARView: View {
+struct DraggableScene: View {
     var body: some View {
         RealityView { content in
-            let box = ModelEntity(
-                mesh: .generateBox(size: 0.1),
-                materials: [SimpleMaterial(color: .blue, isMetallic: true)]
-            )
-            box.position = [0, 0, -0.5]
-            box.components.set(CollisionComponent(
-                shapes: [.generateBox(size: [0.1, 0.1, 0.1])]
-            ))
-            box.components.set(InputTargetComponent())
-            box.name = "draggable"
-            content.add(box)
+            let puck = ModelEntity(mesh: .generateCylinder(height: 0.02, radius: 0.05))
+            puck.generateCollisionShapes(recursive: false)
+            puck.components.set(InputTargetComponent())
+            puck.position = [0, 0, -0.6]
+            content.add(puck)
         }
         .gesture(
             DragGesture()
                 .targetedToAnyEntity()
-                .onChanged { value in
-                    let entity = value.entity
-                    guard let parent = entity.parent else { return }
-                    entity.position = value.convert(
-                        value.location3D,
-                        from: .local,
-                        to: parent
-                    )
+                .onChanged { drag in
+                    guard let parent = drag.entity.parent,
+                          let point = drag.unproject(\.location, to: parent) else { return }
+                    drag.entity.position = point
                 }
         )
     }
 }
 ```
 
-For selection, `CollisionComponent` is the mechanism that makes an entity
-hittable by `RealityViewCameraContent.hitTest`, `SpatialTapGesture`, or
-`targetedToAnyEntity()`. Pair it with `InputTargetComponent`; this enables
-virtual entity picking, not ARKit surface detection.
-
-## Scene Understanding
-
-### Per-Frame Updates
-
-Subscribe to scene update events for continuous processing:
-
-```swift
-RealityView { content in
-    let entity = ModelEntity(
-        mesh: .generateSphere(radius: 0.05),
-        materials: [SimpleMaterial(color: .yellow, isMetallic: false)]
-    )
-    entity.position = [0, 0, -0.5]
-    content.add(entity)
-
-    _ = content.subscribe(to: SceneEvents.Update.self) { event in
-        let time = Float(event.deltaTime)
-        entity.position.y += sin(Float(Date().timeIntervalSince1970)) * time * 0.1
-    }
-}
-```
-
-### Platform Boundaries
-
-On visionOS, ARKit provides a different API surface with `ARKitSession`,
-`WorldTrackingProvider`, and `PlaneDetectionProvider`. These visionOS-specific
-types are not available on iOS. On iOS, RealityKit handles world tracking
-automatically through `RealityViewCameraContent`.
-
-For iOS architecture or migration notes, explicitly name the iOS RealityKit path and handoffs:
-
-- Gate AR with `ARWorldTrackingConfiguration.isSupported`.
-- Host content with `RealityViewCameraContent`.
-- Build scenes from `Entity`/`ModelEntity` and place with `AnchorEntity`.
-- Include a compact `Handoffs` line in architecture/review notes:
-  `CollisionComponent` + `InputTargetComponent` handle RealityKit interaction;
-  `AccessibilityComponent` handles RealityKit entity accessibility metadata;
-  detailed SwiftUI gestures and VoiceOver/Switch Control policy belong to siblings.
-
-Treat existing `SCNView`/`SCNNode` work as either a separate SceneKit path or an
-explicit migration to RealityKit, not a mixed scene graph.
-
-## Common Mistakes
-
-### DON'T: Skip AR capability checks
-
-Not all devices support AR. Showing a black camera view with no feedback
-confuses users.
-
-```swift
-// WRONG -- no device check
-struct MyARView: View {
-    var body: some View {
-        RealityView { content in
-            // Fails silently on unsupported devices
-        }
-    }
-}
-
-// CORRECT -- check support and show fallback
-struct MyARView: View {
-    var body: some View {
-        if ARWorldTrackingConfiguration.isSupported {
-            RealityView { content in
-                // AR content
-            }
-        } else {
-            ContentUnavailableView(
-                "AR Not Supported",
-                systemImage: "arkit",
-                description: Text("This device does not support AR.")
-            )
-        }
-    }
-}
-```
-
-### DON'T: Load heavy models synchronously
-
-Loading large USDZ files on the main thread causes frame drops and hangs.
-The `make` closure of `RealityView` is `async` -- use it.
-
-```swift
-// WRONG -- synchronous load blocks the main thread
-RealityView { content in
-    let model = try! Entity.load(named: "large-scene")
-    content.add(model)
-}
-
-// CORRECT -- async load
-RealityView { content in
-    if let model = try? await ModelEntity(named: "large-scene") {
-        content.add(model)
-    }
-}
-```
-
-### DON'T: Forget collision and input target components for interactive entities
-
-Gestures only work on entities that have both `CollisionComponent` and
-`InputTargetComponent`. Without them, taps and drags pass through.
-
-```swift
-// WRONG -- entity ignores gestures
-let box = ModelEntity(mesh: .generateBox(size: 0.1))
-content.add(box)
-
-// CORRECT -- add collision and input components
-let box = ModelEntity(
-    mesh: .generateBox(size: 0.1),
-    materials: [SimpleMaterial(color: .red, isMetallic: false)]
-)
-box.components.set(CollisionComponent(
-    shapes: [.generateBox(size: [0.1, 0.1, 0.1])]
-))
-box.components.set(InputTargetComponent())
-content.add(box)
-```
-
-### DON'T: Create new entities in the update closure
-
-The `update` closure runs on every SwiftUI state change. Creating entities
-there duplicates content on each render pass.
-
-```swift
-// WRONG -- duplicates entities on every state change
-RealityView { content in
-    // empty
-} update: { content in
-    let sphere = ModelEntity(mesh: .generateSphere(radius: 0.05))
-    content.add(sphere)  // Added again on every update
-}
-
-// CORRECT -- create in make, modify in update
-RealityView { content in
-    let sphere = ModelEntity(mesh: .generateSphere(radius: 0.05))
-    sphere.name = "mySphere"
-    content.add(sphere)
-} update: { content in
-    if let sphere = content.entities.first(
-        where: { $0.name == "mySphere" }
-    ) as? ModelEntity {
-        // Modify existing entity
-        sphere.position.y = newYPosition
-    }
-}
-```
-
-### DON'T: Ignore camera permission
+## Scene updates and platform boundaries
 
-RealityKit on iOS needs camera access. If the user denies permission, the
-view shows a black screen with no explanation.
+### Per-frame work
 
 ```swift
-// WRONG -- no permission handling
-RealityView { content in
-    // Black screen if camera denied
-}
-
-// CORRECT -- check and request permission
-struct ARContainerView: View {
-    @State private var cameraAuthorized = false
-
-    var body: some View {
-        Group {
-            if cameraAuthorized {
-                RealityView { content in
-                    // AR content
-                }
-            } else {
-                ContentUnavailableView(
-                    "Camera Access Required",
-                    systemImage: "camera.fill",
-                    description: Text("Enable camera in Settings to use AR.")
-                )
-            }
-        }
-        .task {
-            let status = AVCaptureDevice.authorizationStatus(for: .video)
-            if status == .authorized {
-                cameraAuthorized = true
-            } else if status == .notDetermined {
-                cameraAuthorized = await AVCaptureDevice
-                    .requestAccess(for: .video)
-            }
-        }
+RealityView { scene in
+    let spinner = ModelEntity(mesh: .generateBox(size: 0.08))
+    scene.add(spinner)
+    _ = scene.subscribe(to: SceneEvents.Update.self) { frame in
+        let step = Float(frame.deltaTime)
+        spinner.orientation *= simd_quatf(angle: step, axis: [0, 1, 0])
     }
 }
 ```
 
-## Review Checklist
-
-- [ ] `NSCameraUsageDescription` set in Info.plist
-- [ ] AR device capability checked before presenting AR views
-- [ ] Camera permission requested and denial handled with a fallback UI
-- [ ] `arkit` required-device capability added when AR is the app's core purpose
-- [ ] 3D models loaded asynchronously in the `make` closure
-- [ ] Entities created in `make`, modified in `update` (not created in `update`)
-- [ ] Interaction notes say `CollisionComponent` makes entities hittable/pickable and pairs with `InputTargetComponent`
-- [ ] Boundary/review notes include a `Handoffs` line naming `AccessibilityComponent` and routing detailed SwiftUI/accessibility policy to siblings
-- [ ] Entity hit tests, `RealityViewCameraContent.ray(...)`, and ARKit real-world surface raycasts are not conflated
-- [ ] ARKit surface raycast placements use `ARSession.raycast(_:)` and `AnchorEntity(raycastResult:)`
-- [ ] `SceneEvents.Update` subscriptions used for per-frame logic (not SwiftUI timers)
-- [ ] Large scenes use `ModelEntity(named:)` async loading, not `Entity.load(named:)`
-- [ ] Anchor entities target appropriate surface types for the use case
-- [ ] Entity names set for lookup in the `update` closure
+Scale motion by `deltaTime`. `subscribe` hands back an `EventSubscription`;
+store it when you plan to cancel it later, or drop it with `_ =` as here.
+
+### What belongs to which platform
+
+- visionOS drives ARKit through `ARKitSession`, `WorldTrackingProvider` and
+  `PlaneDetectionProvider`. None of these exist on iOS.
+- On iOS, `RealityViewCameraContent` runs world tracking for you.
+- An iOS design note should say: gate on `ARWorldTrackingConfiguration.isSupported`,
+  host in `RealityViewCameraContent`, build from `Entity` and `ModelEntity`,
+  place with `AnchorEntity`.
+- Close architecture and review notes with a short **Handoffs** line:
+  `CollisionComponent` plus `InputTargetComponent` for interaction,
+  `AccessibilityComponent` for entity accessibility metadata, and detailed
+  gestures and VoiceOver or Switch Control policy sent to the sibling skills.
+- Existing `SCNView` or `SCNNode` code stays a separate SceneKit path or gets an
+  explicit migration to RealityKit. Never mix the two scene graphs.
+
+## Common mistakes
+
+- **No capability check.** Unsupported devices just show black where the
+  camera should be, and nothing says why.
+
+  ```swift
+  if ARWorldTrackingConfiguration.isSupported {
+      MarbleView()
+  } else {
+      ContentUnavailableView("AR unavailable", systemImage: "arkit",
+                             description: Text("Room tracking needs newer hardware."))
+  }
+  ```
+
+- **Blocking loads.** Loading with the synchronous `Entity.load(named:)` (often
+  written with a forced `try`) on the main thread drops frames or hangs. The
+  make closure is `async`; use `try? await ModelEntity(named:)`.
+- **Missing components.** Without both `CollisionComponent` and
+  `InputTargetComponent`, taps and drags go straight through the entity.
+- **Building in `update`.** SwiftUI calls update again whenever state it reads
+  changes, so creating entities there duplicates them. Create in make, name them,
+  and look them up in update.
+- **Ignoring camera permission.** A denied camera also gives a black screen.
+
+  ```swift
+  import AVFoundation
+
+  func cameraReady() async -> Bool {
+      let status = AVCaptureDevice.authorizationStatus(for: .video)
+      if status == .notDetermined {
+          return await AVCaptureDevice.requestAccess(for: .video)
+      }
+      return status == .authorized
+  }
+  ```
+
+  When it returns `false`, show a `ContentUnavailableView` that explains how to
+  enable the camera.
+
+## Review checklist
+
+- [ ] `NSCameraUsageDescription` is present
+- [ ] AR support is checked before any AR view appears
+- [ ] Camera permission is requested and denial has fallback UI
+- [ ] `arkit` is listed as required hardware only if the whole app is about AR
+- [ ] The make closure loads models with `await`
+- [ ] Make creates entities; update only changes them
+- [ ] Interaction notes explain that `CollisionComponent` provides the hittable shape, paired with `InputTargetComponent`
+- [ ] A Handoffs line mentions `AccessibilityComponent` and sends detailed SwiftUI and accessibility policy to the sibling skills
+- [ ] Entity hit tests, `ray(...)` and ARKit surface raycasts are kept distinct
+- [ ] Surface placement uses `ARSession.raycast(_:)` with `AnchorEntity(raycastResult:)`
+- [ ] Per-frame logic uses `SceneEvents.Update`, not SwiftUI timers
+- [ ] Large scenes load with async `ModelEntity(named:)`, not `Entity.load(named:)`
+- [ ] Anchor targets match the kind of surface the feature needs
+- [ ] Entities that update looks up have names
 
 ## References
 
-- Read [references/realitykit-patterns.md](references/realitykit-patterns.md) for physics, animations, lighting, ECS, accessibility, and performance patterns.
-- [RealityKit framework](https://sosumi.ai/documentation/realitykit)
-- [RealityView](https://sosumi.ai/documentation/realitykit/realityview)
-- [RealityViewCameraContent](https://sosumi.ai/documentation/realitykit/realityviewcameracontent)
-- [RealityViewCamera](https://sosumi.ai/documentation/realitykit/realityviewcamera)
-- [Entity](https://sosumi.ai/documentation/realitykit/entity)
-- [ModelEntity](https://sosumi.ai/documentation/realitykit/modelentity)
-- [AnchorEntity](https://sosumi.ai/documentation/realitykit/anchorentity)
-- [ARKit framework](https://sosumi.ai/documentation/arkit)
-- [ARKit in iOS](https://sosumi.ai/documentation/arkit/arkit-in-ios)
-- [Verifying Device Support and User Permission](https://sosumi.ai/documentation/arkit/verifying-device-support-and-user-permission)
-- [ARWorldTrackingConfiguration](https://sosumi.ai/documentation/arkit/arworldtrackingconfiguration)
-- [ARRaycastQuery](https://sosumi.ai/documentation/arkit/arraycastquery)
-- [ARSession.raycast(_:)](https://sosumi.ai/documentation/arkit/arsession/raycast(_:))
-- [Loading entities from a file](https://sosumi.ai/documentation/realitykit/loading-entities-from-a-file)
+- [Pattern catalogue](references/realitykit-patterns.md): physics, animation, materials and lighting, custom components and systems, occlusion, a SwiftUI model viewer, entity accessibility, performance
+- [RealityKit](https://developer.apple.com/documentation/realitykit)
+- [RealityView](https://developer.apple.com/documentation/realitykit/realityview)
+- [RealityViewCameraContent](https://developer.apple.com/documentation/realitykit/realityviewcameracontent)
+- [RealityViewCamera](https://developer.apple.com/documentation/realitykit/realityviewcamera)
+- [Entity](https://developer.apple.com/documentation/realitykit/entity)
+- [ModelEntity](https://developer.apple.com/documentation/realitykit/modelentity)
+- [AnchorEntity](https://developer.apple.com/documentation/realitykit/anchorentity)
+- [ARKit](https://developer.apple.com/documentation/arkit)
+- [ARKit on iOS](https://developer.apple.com/documentation/arkit/arkit-in-ios)
+- [Device support and permission checks](https://developer.apple.com/documentation/arkit/verifying-device-support-and-user-permission)
+- [ARWorldTrackingConfiguration](https://developer.apple.com/documentation/arkit/arworldtrackingconfiguration)
+- [Raycast query type](https://developer.apple.com/documentation/arkit/arraycastquery)
+- [Session raycast method](https://developer.apple.com/documentation/arkit/arsession/raycast(_:))
+- [Entity loading article](https://developer.apple.com/documentation/realitykit/loading-entities-from-a-file)