sphr-tour

name	sphr-tour
description	Build or fix SPHR animated guided tours, including tourpoints, camera moves, text/media overlays, annotations, models, audio, and extra transitions.
argument-hint	["tour/config path or behavior"]
allowed-tools	Read Write Glob Bash(ls *) Bash(rg *) Bash(node .claude/scripts/project/asset-inventory.mjs *) Bash(node .claude/scripts/project/validate-bootstrap.mjs *) Bash(node .claude/scripts/tour/create-bootstrap.mjs *) Bash(node .claude/scripts/project/verify-app.mjs *) Bash(npm run typecheck *) Bash(npm run build *)
agent	sphr-tour

Use this for guided-tour behavior.

Tour Data

SPHR supports tour_data.spaces and legacy tourmodels.

Tourpoint fields:

{
  "id": "point-1",
  "text": "Primary tour text",
  "secondaryText": "Optional detail",
  "textPosition": "left",
  "viewMode": "FPV",
  "targetType": "NODE",
  "nodeUUID": "entry",
  "position": { "x": 0, "y": 1.5, "z": 4 },
  "rotation": { "azimuth": 0, "polar": 0 },
  "zoom": 0,
  "files": [],
  "models": [],
  "annotations": [],
  "sounds": [],
  "extra": "projectToSplats"
}

Runtime behavior:

• position, rotation, zoom, and viewMode drive camera pose.
• files render media in TourOverlay.
• models control SceneGraphLayer.showOnly.
• annotations control AnnotationLayer.show.
• sounds are passed to AudioController.
• extra maps to project-specific transitions such as shrinkToPoints, projectToSplats, and nightMode.

Implementation Rules

• Prefer data changes over hard-coded point IDs.
• If a new extra is reusable, implement it in a named runtime method or layer.
• Keep mobile layout in mind; tour copy and nav buttons must not collide with HUD controls.
• Do not hide broken timing behind instant jumps. Animated tours should visibly transition unless the user requests otherwise.

Verification

node .claude/scripts/project/validate-bootstrap.mjs <config>
npm run typecheck
npm run build
node .claude/scripts/project/verify-app.mjs --url "http://localhost:3000/?config=/configs/<config>.json" --screenshots

Final response should report tourpoint count, key transitions/extras, media/model/audio hooks touched, and verification outcome.