# VR Tours — links and hosted 360° tours (Shared · Project Catalogue)

> 📍 Part of the project catalogue doc set — the map and routing table is
> [start-here.md](/docs/modules_handbook/shared/project-catalogue/start-here.md).

**Context:** a sub-module of [Project Catalogue](/docs/modules_handbook/shared/project-catalogue/readMe.md) · **Nav:** the **VR Tours** tab on a catalogue project's Show page (`/manage/property/catalog/{uuid}?tab=vr-tours`), and a hosted tour's editor page (`/manage/property/catalog/{uuid}/vr-tours/{tourId}`, reached from that tab); buyers see the **VR360 Tour** tab on the public Malaysian project page (`/my/projects/{slug}#vr-tours`), the selected unit's card, and a hosted tour's own page (`/my/projects/{slug}/tours/{tourUuid}`) · **Used by:** Project Catalogue (admin), the public project detail page and the Area Guide drawer (same props).

## What it does

Lets an admin attach **on-site / in-building 360° VR tours** — a walkthrough of the lobby, a show
unit, the facilities — to a catalogue project. Two types (`CatalogVrTour::TYPES`):

- **External link** (`TYPE_LINK`) — a **title** and a **URL** to a tour hosted elsewhere (Matterport,
  Kuula, Realsee, the developer's own viewer). Nothing is uploaded or rendered here.
- **Our 360° photos** (`TYPE_HOSTED`, 2026-10-22 — owner: *"I dont want to be realsee link, I have
  original images"*) — the admin uploads the unit's own 360° photographs, one per room, and places
  **arrows** on each photo that walk the reader to the next room. They are stored in our own bucket
  and shown on **this platform's own tour page**. Floorplan / 3D-model views (what Realsee builds from
  its scan) are deliberately not offered — owner's call, same day.

Either type may be tied to **one layout** (a floor plan buyers see). On the public page each tour is
one row of the VR360 Tour tab — the title and a **View** button that opens it in a new browser tab
(`target="_blank" rel="noopener noreferrer"`); a tour tied to a layout ALSO appears as a button on
that layout's selected-unit card (Units tab). The raw URL is never printed to a buyer. A project with
no tours shows no tab, and a hosted tour with no photo yet is not listed. Guests see it — like the
360° Aerial tab, it is marketing, not a member benefit.

⚠️ **Not the same thing as [VR360 Aerial Panoramas](/docs/modules_handbook/shared/project-catalogue/vr360/readMe.md).**
That sub-module RENDERS an aerial view from Google 3D Tiles and stores the image. This one stores
someone else's link to the INSIDE of the building. Separate table, separate tab, separate code.

## How it works

- **Table `catalog_vr_tours`** — `catalog_project_id` + `catalog_project_uuid`, `title` (191),
  `url` (2048), `position`, blame columns, soft deletes. Model `Src\Analysis\Reference\CatalogVrTour`,
  relation `CatalogProject::vrTours()`.
- **It is a CATALOGUE table** (owner's ruling, 2026-09-26 — a project's tours are the same on every
  platform), so its migration lives in
  [`database/migrations/catalogue/`](/database/migrations/catalogue/README.md)
  (`2026_09_26_120000_create_catalog_vr_tours.php`) and is applied to both the master and each
  site's own copy. ⚠️ **The Hub must run `php artisan migrate --path=database/migrations/catalogue
  --database=catalogue` before the tab works against the master** — until then every read of a
  master project fails with "table not found".
- **Children follow their project.** Always read through `CatalogVrTour::forProject($catalogue)`,
  which asks on the project's own connection (master, or the site DB for a platform-created
  project) and returns display order (`position`, then `id`). It also matches
  `catalog_project_uuid IS NULL OR = the project's uuid`, so a stale integer after a master re-key
  cannot show another building's tours — the same guard `approvedVrBake()` uses.
- **Writes** go through `Src\Analysis\Repositories\CatalogVrTourRepository` (`create` appends at the
  end, `update`, `reorder`, `delete` = soft delete), each in a transaction on the project's
  connection. A tour is always resolved INSIDE its project (`findTour()` in the controller), so a
  tour id from another project 404s; `reorder` silently drops ids the project does not own.
- **Routes** (`routes/web.php`, inside `manage.property.catalog.*`), all
  `permission:manage-projects` + **`catalogue.edit`** (the domain gate — writes to a master row are
  allowed only from `CATALOGUE_EDIT_DOMAINS`):

  | Method | URI | Name |
  |---|---|---|
  | POST | `{id}/vr-tours` | `vr-tours.store` |
  | PUT | `{id}/vr-tours/order` (declared before `{tourId}`) | `vr-tours.order` |
  | PUT | `{id}/vr-tours/{tourId}` | `vr-tours.update` |
  | DELETE | `{id}/vr-tours/{tourId}` | `vr-tours.destroy` |
  | GET | `{id}/vr-tours/{tourId}` (hosted tour editor; no `catalogue.edit` — read-only off-domain) | `vr-tours.show` |
  | POST | `{id}/vr-tours/{tourId}/scenes` | `vr-tours.scenes.store` |
  | PUT | `{id}/vr-tours/{tourId}/scenes/order` (before `{sceneId}`) | `vr-tours.scenes.order` |
  | PUT | `{id}/vr-tours/{tourId}/scenes/{sceneId}` | `vr-tours.scenes.update` |
  | PUT | `{id}/vr-tours/{tourId}/scenes/{sceneId}/links` | `vr-tours.scenes.links.update` |
  | DELETE | `{id}/vr-tours/{tourId}/scenes/{sceneId}` | `vr-tours.scenes.destroy` |

- **Validation** — `StoreCatalogVrTourRequest` (Update extends it): `type` one of `TYPES` (default
  link), title required ≤191, `floor_plan_uuid` optional (must be one of THIS project's visible
  layouts — checked in the controller). For a LINK the url is required ≤2048 and
  **`url:http,https`** — the value becomes a link buyers click, so a `javascript:` URL must never be
  stored; a hosted tour carries none. On update the type is the STORED tour's, never the payload's
  (`UpdateCatalogVrTourRequest::prepareForValidation`), so a link cannot drop its URL by claiming
  to be hosted. A tour never changes type.
- **Public page** — `ProjectDetailController::malaysiaPageProps()` sends `vrTours`
  (`[{ title, url, floor_plan_uuid }]`, nothing else) from the private `vrTourLinks()`. The prop is declared in
  `Components/ProjectDetail/projectDetailProps.js` — **an undeclared prop is silently dropped** by
  the page's `v-bind="props"` — and rendered by the `#tab-vr-tours` slot in
  `ProjectDetailContent.vue`, placed right after 360° Aerial.
- **Delete / cleanup** — `CatalogProjectRepository::delete()` soft-deletes the project's tours;
  `ProjectCatalogueMergeService::retainedDependencies()` lists "VR tour links" as a blocker, so the
  orphan sweep never deletes a canonical an admin has curated tours on.
- **Not covered (yet):** the Hong Kong and old-UAE detail pages do not show tours (a UAE v2 project
  takes the Malaysian page, so it does); `catalogue:export` packages do not carry these tables (a
  COPY site's mirror does, since it copies every master table).

### Hosted tours (our own 360° photos, 2026-10-22)

- **Tables** (catalogue migration `2026_10_22_120000_add_hosted_scenes_to_catalog_vr_tours.php`):
  - `catalog_vr_tours` gains `uuid` (public id of the tour page; existing rows backfilled), `type`
    (`TYPE_LINK` 1 / `TYPE_HOSTED` 2, default 1), `catalog_floor_plan_id` + `catalog_floor_plan_uuid`
    (the optional layout), and `url` becomes nullable (a hosted tour has none).
  - `catalog_vr_tour_scenes` — one photograph (`CatalogVrTourScene`): `uuid`, `catalog_vr_tour_id`,
    `title` (the room), `media_id`, `width`/`height`, `yaw`/`pitch` (where its camera opens, radians;
    null = the photo's centre), `position` (walking order — **the first is where the tour opens**),
    blame. Max `CatalogVrTourScene::MAX_SCENES` (30) per tour. HARD-deleted with its file.
  - `catalog_vr_tour_links` — an arrow (`CatalogVrTourLink`): `catalog_vr_tour_scene_id` (the photo it
    sits on), `target_scene_id`, `yaw`/`pitch` (the point on the sphere), `label` (≤ 80; blank = the
    arrow is drawn as the icon alone — the room's name stays its accessible name), `position`. Max 30 per photo. A photo's arrows are saved as one list and
    replaced whole.
- **Children follow their project**, like the tour itself: scenes and arrows live on the tour's
  connection (`KeepsRelatedConnections`), and a scene's photograph is a `media` row stored with
  `MediaContext::forOwner($tour)` — the master's `media` for a master project, the site's for one this
  platform created. Read it with `$scene->storedMedia()` (a `MasterMedia` on the scene's connection),
  never a relation — `MasterMedia` is pinned to the catalogue and would miss a site-created project's file.
- **Upload** (`CatalogVrTourSceneController::store`) reuses the Area Guide's panorama pipeline:
  `AreaGuideUpload(PANORAMA)` refuses anything that is not a complete **2:1 JPEG/PNG, 1024–20000 px
  wide** within `area_guide_content.panorama_max_kb` (50 MB); `PanoramaImage::normalise()` re-encodes
  it to a JPEG no wider than 8192 px (4–6 MB); `MediaService::storeFromPath()` stores it; the scene row
  is created in a transaction; a failed create deletes the file it just stored. The editor uploads a
  multi-file pick one request at a time (each file → one room, named after the file).
- **Delete** a photo: its arrows (on it AND pointing to it) and the row go in one transaction
  (`CatalogVrTourSceneRepository::delete()`), then `MediaService::delete()` removes the file, outside
  it — a failure is logged; MediaService keeps a durable intent to retry. Deleting the whole tour is
  the existing SOFT delete: its photos and their files stay, recoverable.
- **Editor page** `Pages/Manage/Property/Catalog/VrTourEditor.vue`: upload, rename, reorder, delete
  photos; **Add arrow** → click the spot on the photo → pick the room it leads to (+ optional label)
  → **Save arrows**; **Set start view here** saves where the current photo opens. Viewable wherever the
  record is; editable only where `canEdit()` passes (the catalogue admin domain) — off it the page is
  read-only and says so.
- **Public tour page** `GET /{country}/projects/{slug}/tours/{tourUuid}`
  (`main.site.projects.tours.show`, `Main\Site\ProjectVrTourController::show` →
  `Pages/Main/Site/ProjectVrTour.vue`): the viewer, the arrows, a strip of every room. Visible to whoever
  may see the project page (`CatalogueDetailService::viewerMaySee` — published + listed, or a staff
  preview); otherwise 404. A tour with no photo is 404 too.
- **Photographs are served same-origin**: `GET /vr-tour-media/{sceneUuid}` (`main.site.vr-tour-media`,
  `ProjectVrTourController::media`) streams the file — Photo Sphere Viewer reads it into a WebGL
  texture, which a signed bucket URL (no CORS headers) cannot feed; the same reason as `/vr-media`.
  Same visibility rule; `Cache-Control: public, immutable` for a published project (a photo is never
  re-imaged — a new photo is a new scene), `private` for a preview.
- **The viewer** `Components/Vr/VrTourViewer.vue`: ONE Photo Sphere Viewer for the whole tour
  (`setPanorama` with a fade to change room — a WebGL context per photo would exhaust the browser's
  cap), arrows drawn with the Area Guide's `linkMarkerHtml` (`utils/areaGuide/panoramaFlight.js`). View
  mode follows an arrow; edit mode reports clicks (`place`) and selects arrows instead. No navbar (owner, 2026-10-22): zoom is the wheel or a pinch, and while the
  reader zooms a badge shows the magnification against the opening view (`1.2×`; field of view
  90°–30°, opening at 60°, so 0.7×–2.0×). An arrow with no label of its own is drawn as the icon alone.
- **Project page**: `vrTourLinks()` sends `[{ title, url, floor_plan_uuid }]` — a hosted tour's `url` is
  its tour page; a hosted tour with no photo is left out. `ProjectDetailContent` filters the tours tied
  to the selected layout and passes them through `ProjectUnitsPriceTab` to `SelectedUnitCard`.
- ⚠️ **Deploy: the Hub must run `php artisan migrate --path=database/migrations/catalogue
  --database=catalogue`.** Until it does, reads stay safe — `CatalogVrTour::hostingAvailable($connection)`
  (one `hasTable` per connection per request) makes the project page and the Show tab read every tour as
  a link, and the tour page / `/vr-tour-media` answer 404 instead of querying a table that is not
  there (`CatalogVrTourScene::findByUuid` skips such a connection), so nothing 500s — but **every tour WRITE on the master fails** (the new `uuid` / `type`
  columns do not exist yet), links included.

## Reference usage

```php
use Src\Analysis\Reference\CatalogVrTour;
use Src\Analysis\Repositories\CatalogVrTourRepository;
use Src\Analysis\Repositories\CatalogVrTourSceneRepository;

// Read — always on the project's own connection, in display order.
$tours = CatalogVrTour::forProject($catalogue)->get();

// Write a link — nested input keyed by the model, per GUIDELINES.
$data['catalog_vr_tour']['type'] = CatalogVrTour::TYPE_LINK;
$data['catalog_vr_tour']['title'] = 'Show unit Type A';
$data['catalog_vr_tour']['url'] = 'https://my.matterport.com/show/?m=abc';
$tour = app(CatalogVrTourRepository::class)->create($catalogue, $data);

// A hosted tour's photos and arrows: see CatalogVrTourSceneController for the
// store → attach → clean-up-on-failure order around MediaService.
app(CatalogVrTourSceneRepository::class)->saveLinks($scene, [
    ['target_scene_id' => $bedroom->id, 'yaw' => 1.2, 'pitch' => -0.1, 'label' => 'Bedroom'],
]);
```

## Related files

- `database/migrations/catalogue/2026_09_26_120000_create_catalog_vr_tours.php`, `…/2026_10_22_120000_add_hosted_scenes_to_catalog_vr_tours.php`
- `src/Analysis/Reference/CatalogVrTour.php`, `CatalogVrTourScene.php`, `CatalogVrTourLink.php`, `CatalogProject::vrTours()`
- `src/Analysis/Repositories/CatalogVrTourRepository.php`, `CatalogVrTourSceneRepository.php`
- `app/Http/Controllers/Manage/Property/CatalogVrTourController.php` (incl. the editor page `show`), `CatalogVrTourSceneController.php`
- `app/Http/Controllers/Main/Site/ProjectVrTourController.php` — the public tour page + `/vr-tour-media/{uuid}`
- `app/Http/Requests/Manage/Property/{Store,Update}CatalogVrTourRequest.php`, `ReorderCatalogVrToursRequest.php`, `{Store,Update}CatalogVrTourSceneRequest.php`, `ReorderCatalogVrTourScenesRequest.php`, `SaveCatalogVrTourLinksRequest.php`
- `resources/js/Components/Vr/VrTourViewer.vue`, `Pages/Manage/Property/Catalog/VrTourEditor.vue`, `Pages/Main/Site/ProjectVrTour.vue`
- `resources/js/Components/ProjectDetail/SelectedUnitCard.vue`, `ProjectUnitsPriceTab.vue` — the layout's tour button
- `app/Http/Controllers/Manage/Property/CatalogController.php` — `vrTours` Show prop
- `app/Http/Controllers/Main/Site/ProjectDetailController.php` — `vrTours` page prop, `vrTourLinks()`
- `resources/js/Pages/Manage/Property/Catalog/Partials/Tabs/VrToursTab.vue`, `Show.vue`
- `resources/js/Components/ProjectDetail/ProjectDetailContent.vue`, `projectDetailProps.js`
- `tests/Feature/Property/CatalogVrTourTest.php`
