# Area Guide enhancement — session handover **Snapshot:** 2026-09-14, Asia/Kuala_Lumpur. Workspace: `C:\Users\zhish\work\petav3`. ## What it does This is the entry point for a new session continuing the Area Guide work. It preserves the material discussion, confirmed decisions, implementation state, evidence and next steps. It is a curated handover, not a verbatim chat transcript or a production deployment record. **Current outcome:** the Malaysia-first local implementation and the recorded local functional checks are complete. Production master cutover, a common cloud bucket, actual two-site propagation, representative original assets and physical-device acceptance remain pending. Do not translate "local checks passed" into "everything is production verified". The handover-writing turn changed documentation only. It checked documentation links and diff whitespace; it did not rerun application tests or builds. The results in section 7 belong to the completed implementation run on September 13–14. > **2026-09-15 (after this handover):** the traced building boundaries described below were > replaced by click-placed building markers (`area_guide_hotspots`), panoramas gained a > "little planet" intro, blur-and-crossfade flights with preloading, building models on the map > can link custom buildings (rotate / move / resize handles, automatic basemap clipping), and > automatic return arrows wait for confirmation. Read the > [map readMe](/docs/modules_handbook/shared/project-catalogue/area-guide-map/readMe.md) for the > current state; the sections below are the 2026-09-14 snapshot. **A later audit-remediation pass (2026-09-14)** fixed the defects and stale claims that review found across the registry, map, reader, shared-media and catalogue-federation code, and re-ran the automated checks. Its scope, results, pre-existing failures and new open items are in [section 7's remediation checkpoint](#remediation-checkpoint--2026-09-14) and, in full, in the [validation record](/docs/modules_handbook/shared/project-catalogue/area-guide-map/validation.md#remediation-checkpoint--2026-09-14). That pass ran **no browser session, no build and no production or master write**, so none of the pending external acceptance below moved. ## How it works ### 1. Start here and respect the workspace 1. Read `/AGENTS.md`, `/AGENTS.local.md` and `/GUIDELINES.md` from the actual checkout. The user explicitly requires all three. Read more-specific instructions if present. 2. Read [the handbook conventions](/docs/modules_handbook/README.md) and [the catalogue entry map](/docs/modules_handbook/shared/project-catalogue/start-here.md). 3. Read the requirements and final acceptance record linked in section 2 before proposing unfinished work. Some historical sections intentionally retain earlier pending results; use the current requirement states and final acceptance record for the latest outcome. 4. Inspect current code and `git status` before editing. The user runs multiple sessions; the working tree contains many pre-existing and concurrent changes. No implementation commit was created by this session. Do not treat every dirty file as part of this feature, reset unrelated work, or overwrite another session's changes. 5. Respond in simple Mandarin, retaining English technical names and expanding abbreviations. Repository code, comments and documentation follow GUIDELINES.md's English requirement. Ask about material missing product decisions; do not reopen decisions already confirmed. 6. Preserve repository patterns: dedicated Form Requests, explicit controller field mapping, repositories for writes, transactions on the actual owning connection, state constants, reusable form/modal components and `withSuite()` for Manage links. Read a shared service's handbook before changing its usage. Update affected documentation with code changes. This handover grants no new production access. Inspect private configuration without printing credentials, tokens, authentication cookies or environment backups. No production/master migration or write was performed during this work. ### 2. Which document records what? | Document | Read it for | |---|---| | [This handover](/docs/modules_handbook/shared/project-catalogue/area-guide-map/handover.md) | Discussion summary, latest checkpoint, local context and the next-session starting point | | [Requirements checklist](/docs/modules_handbook/main/area-guide/catalogue-map-requirements.md) | R1–R16 requirements, constraints, acceptance criteria, D1–D7 decisions, module relationships and original investigation | | [Shared-content plan](/docs/modules_handbook/shared/project-catalogue/area-guide-shared-content-plan.md) | Why content belongs to one live master, current-site editing, database/storage ownership, local versus shared records and production boundaries | | [Map handbook](/docs/modules_handbook/shared/project-catalogue/area-guide-map/readMe.md) | Implemented feeds, uploads, placement, polygon editor, permissions, renderer limits, file lifecycle and production runbook | | [Validation record](/docs/modules_handbook/shared/project-catalogue/area-guide-map/validation.md) | Exact browser journeys, automated selections, build results, cleanup, failures and explicitly unverified items | | [Registry handbook](/docs/modules_handbook/shared/project-catalogue/area-guide-registry/readMe.md) | Country/region/area schema, editing, idempotent import, existing consumers and local setup | | [Shared Project Detail](/docs/modules_handbook/shared/project-detail/readMe.md) | One full Malaysian detail component used by the standalone page and map drawer; navigation/request isolation and country adapter limits | | [Media handbook](/docs/modules_handbook/shared/media/readMe.md) | Canonical MediaService usage, shared ownership, private delivery and cleanup | | [Catalogue start-here](/docs/modules_handbook/shared/project-catalogue/start-here.md) | The whole catalogue documentation map, database traps and task-specific reading routes | Planning documents contain investigation-era descriptions as well as current checkpoints. They are not substitutes for reading the referenced code. Do not copy an old "not implemented" row from the explicitly historical foundation section as the current task status. ### 3. Discussion and confirmed product decisions | Topic | Confirmed outcome and reasoning | |---|---| | Original investigation | Read Area Guide, Walkable Session, Area Tutorials, route-export audit, Sales Projects, Project Catalogue and Media documentation, then verify the named code paths. The user wanted to understand both frontend entry points and module relationships before redesign. | | Learning Hub navigation | Hide only the Area Guide tab button. Keep the direct page reachable under its existing access rules. Do not infer anonymous public access. | | Geographic scope | Malaysia first. Country/region/area presentation and map profiles come from data so later Hong Kong and UAE (United Arab Emirates) use the same new map/media functions. Country-specific learning and financial-analysis logic does not automatically become universal. | | Ownership | Shared authored Area content, project model assets, placements, panoramas, videos and annotation metadata belong to the common master database. Actual files must also live in common private storage. | | Editing entry | The user rejected a separate central backend/project folder or redirect. Every site uses the same codebase and its own existing Manage login/editor, reading and writing the same live shared content. | | Cross-site changes | An edit should be reflected on participating sites when they next load or refresh. No per-site divergent writable copy or mirror is intended. Already-open browser push updates are not implemented. Shared data updates do not deploy frontend code to separate deployments. | | User's deployment description | Production is `propertylabglobal.com`; other sites connect to the same master project database and use the same codebase. This topology was supplied by the user, not audited on actual deployments. | | Project source | Use published Project Catalogue records, including eligible new launches and subsale. Sales/working project status is not catalogue publication. | | Detail drawer | Reuse complete detail Tabs, initially opening Overview. Editing one shared component should affect the standalone page and drawer. Preserve the underlying map, camera and page address. | | Building models | Admin uploads a model associated with a catalogue project and places it on the map. Position, heading, elevation and scale are editable; several towers/placements are supported. Clicking the model opens project details. | | Panorama location | Admin clicks a map location, uploads a complete panorama and gets a stable viewing link. A panorama can identify more than one catalogue project. | | Panorama access | Admin-only now, including entry points, page, original image and building annotations. Opening to members is a future policy change. Publication must not override audience restrictions. | | Whole-building selection | The user explicitly chose clicking any part of the annotated building. Admin manually traces its boundary and then searches/binds a published catalogue project. Name-only hotspots are insufficient. Automatic building detection was not requested for this release. | | Video location | Admin uploads a video and separate cover. The map shows its cover; a click opens a player with native controls. | | File formats | Reuse MediaService. The user did not supply representative model/video formats or size profiles; architecture was not blocked on that questionnaire. Current supported formats and configurable limits are implementation defaults, not confirmation that arbitrary formats can be converted. | | Working method | Prepare requirements first, clarify material conflicts, implement in stages, preserve unrelated functionality, run relevant tests/builds and distinguish verified behavior from unfinished or untested behavior. | The user's sample panorama was 12000 by 6000 pixels before chat resizing. The supplied [Cochrane tour reference](https://storefrontcochranevrprod.z23.web.core.windows.net/) illustrated the desired viewing experience; importing that tour, copying its assets or reproducing every tour feature was not agreed. An original image file is still needed for large-image acceptance. ### 4. Module boundaries to preserve | Module | Owns and relates to | |---|---| | Sales / working Projects (`projects`) | Site-local sales/marketing work, groups, bookings and commercial settings. A working project may reference Catalogue, or be custom. It is not the shared map's canonical project store. | | Project Catalogue (`catalog_projects`) | Canonical project identity, publication, geography, developer, floor plans, media and facts. Associations use its UUID (Universally Unique Identifier). | | Area Guide | Country/region/area registry and the exploratory map, now including shared models, locations and whole-building panorama annotations. | | Area Tutorials | Site-local ordered lessons, stops, scripts and route exports. They may reference areas/catalogue projects; they do not own every model or map location. | | Walkable Session | Existing station/visit learning flow. Keep its behavior and local learning records; selecting a building must not submit a lesson, visit or quiz. | The user earlier asked whether local guide/tutorial data was empty. Do not carry that question forward as a current database fact. The registry is now populated; synthetic map assets were removed after tests. Tutorial table counts were not re-audited in the handover-writing turn. ### 5. Implemented local functionality - Database-backed registry, Manage editing, repeatable import preserving existing keys/admin edits, and integrations with Guide/tutorial selectors/Road/narration/chat/walkable consumers. - Published/listed, country-restricted project feeds with shared/local identity deduplication, bounded viewport queries, clustering and cancellation of stale requests. Shared asset and marker bindings use shared catalogue projects; a site-only project can still have a map pin. - A shared complete Malaysian `ProjectDetailContent.vue` and canonical backend prop builder. Both hosts retain existing access rules, which since the remediation include the site listing and not publication alone. The drawer isolates tab/address state and prevents Overview opening from triggering deep-analysis prefetch. Hong Kong/UAE full drawer adapters remain future work; their existing standalone pages are the fallback, and the endpoint's 422 refusal now carries that page's link so the drawer offers a real destination instead of dead-ending. - Private self-contained GLB (binary glTF, Graphics Library Transmission Format) model upload, preview, persisted transforms, multiple placements, actual mesh selection, renderer cleanup and a basemap 3D-object toggle for overlap inspection. Individual basemap-building clipping is not implemented. Geometry/anchor conventions are in the map handbook. - Admin-only panorama upload/view link, click-placed markers (a project, a custom building or — since 2026-09-15 — a location video; the traced polygons were retired 2026-09-15), catalogue search, edit/remove/undo, initial view, image-version checks and optimistic edit conflicts. Saving visible markers preserves the ones the current site cannot see. - Video points (2026-09-15): the same location-video asset is placeable on the map and inside a panorama, uploadable from either editor through the one `assets.store` endpoint, opened on its own full-screen page `/manage/area-guide/videos/{uuid}` in a new tab (readers: inline in the guide modal), and refused deletion while markers use it. Both editors' project/building/video links go through `Src\AreaGuide\Services\AreaGuideLinks`. Watch progress is NOT recorded — see §8. - Video upload with independent cover, actual codec inspection, protected streaming with byte ranges, user-initiated playback and native seek/fullscreen controls. - Shared MediaService context, dedicated media/outbox tables, safe replacement and scoped cleanup. Actor snapshots include site identity so site-local administrator IDs cannot be mistaken for the same person across sites. Snapshots are not a full immutable audit history. - Explicit administrator/permission gates, separate draft/publication/audience controls and fail-closed database ownership checks. Sales staff do not become administrators merely by receiving a permission with a matching name. Current defaults: self-contained GLB 2.0 models, JPEG/PNG complete 2:1 panoramas, H.264 MP4 video with AAC (Advanced Audio Coding) audio or no audio, and JPEG/PNG/WebP covers. Models and panoramas default to 50 MiB (mebibytes), videos to 80 MiB and covers to 10 MiB. There is no automatic conversion, video transcoding or photograph-to-model generation. Read the validator and configuration before changing support or promising a particular source file. The MP4 requirement is now enforced by the file's **ftyp major brand**, not only by the demuxer name ffprobe reports — QuickTime, 3GPP/3GPP2 and Apple audio-only brands, and a file declaring no brand, are refused. Tell administrators who shoot on a phone: an iPhone/QuickTime `.mov` must be converted to MP4 before upload; it used to be accepted and stored as `video/mp4`. This also raises an `ffprobe` floor — it must understand the `format_tags` section, or the rule rejects every video. ### 6. Local environment and visible pages | Item | Last recorded state | |---|---| | Site | `http://petav3.test`, site database `petav3` | | Area Guide authoring | Dedicated loopback-only `petav3_area_guide`, connection `area_guide_local` | | Disposable tests | `petav3_area_guide_testing`; all site/master/reference test connections were explicitly redirected to disposable local fixtures | | Production master | Existing read-only access; unchanged. Do not repurpose credentials or run production migrations merely to resume local testing. | | Source/flags | `AREA_GUIDE_CONTENT_SOURCE=database`, `AREA_GUIDE_CONTENT_CONNECTION=area_guide_local`, `AREA_GUIDE_CONTENT_EDITING=true`, `AREA_GUIDE_MAP_ENABLED=true` | | Local media | `AREA_GUIDE_MEDIA_DISK=area_guide_local`, private root `storage/app/area-guide-private` | | Video inspection | Local `AREA_GUIDE_FFPROBE` points to the installed Windows `ffprobe.exe`; verify that executable before a new video test | | Schema/import | Nine tables including the migration ledger. Registry import: 3 countries, 6 regions, 24 areas; repeat import preserved all 33 records. | | Post-acceptance data | Recorded active assets, placements, polygons and media rows: zero. This was deliberate cleanup, not a lost upload or an empty registry. | Local page entry points: - [Manage registry](http://petav3.test/manage/area-guide) - [Manage map editor](http://petav3.test/manage/area-guide/map) - [Direct reader Guide](http://petav3.test/property/academy?tab=area-guide) - Panorama links are generated as `/manage/area-guide/panoramas/{uuid}` after upload. - [Standalone detail reference](http://petav3.test/my/projects/binastra-cochrane#overview) Only these new shared schema migrations were applied to the isolated local Area Guide database: `2026_09_13_160000_create_area_guide_registry.php`, `2026_09_13_220000_create_area_guide_media.php` and `2026_09_13_230000_create_area_guide_map_assets.php`, all under `database/migrations/catalogue/`. Site permissions have their own `database/migrations/2026_09_13_200001_grant_area_guide_permissions.php` migration. Follow the exact production runbook later; do not run the entire catalogue migration history, copy/reseed commands or `migrate:fresh` on the master. Local PHP used `C:\laragon\bin\php\php-8.4.15-Win32-vs17-x64\php.exe` and Node used `C:\laragon\bin\nodejs\node-v22\node.exe`. Treat executable paths, environment settings, database counts and service availability as a snapshot and verify before relying on them. Do not stop another session's Vite server or remove `public/hot` to simplify a test. ### 7. Completed verification and important qualifications | Evidence | Result from the implementation run | |---|---| | Existing Guide/registry/tutorial/project-preview regression selection | 61 tests, 952 assertions passed | | Expanded map workflow selection | 22 tests, 287 assertions passed (superseded by the 28 / 356 run in the remediation checkpoint below) | | Shared media context isolation | 12 tests, 63 assertions passed | | Spherical polygon validation | 24 tests, 38 assertions passed | | Related frontend tests | 216 non-guard tests plus 20 source-guard tests passed across batches; 236 distinct tests | | Build | Client and server-rendering builds passed; client was rebuilt after the final marker accessibility fix | | Other checks | PHP style, migration constants, suite-link guard and diff whitespace passed | The validation record also lists an earlier overlapping 44-test selection and focused reruns. Do not sum overlapping counts. The existing PHPUnit configuration deprecation and large build-chunk warnings remain. The source-guard scan initially timed out; caching each source once fixed repeated disk reads without weakening either rule or skipping assertions. #### Remediation checkpoint — 2026-09-14 The audit-remediation pass re-ran automated checks only. Headline results — the full table, including what each fix changed, is in the [validation record](/docs/modules_handbook/shared/project-catalogue/area-guide-map/validation.md#remediation-checkpoint--2026-09-14): | Evidence | Result | |---|---| | Map HTTP workflow (`AreaGuideMapAssetsTest`) | 28 tests / 356 assertions passed (was 22 / 287) | | Area Guide unit selection (`tests/Unit/AreaGuide`) | 92 tests / 492 assertions passed | | Manage registry (`AreaGuideContentTest`) and Area Tutorials | 12 / 135 and 22 / 210 passed | | Portal Area Guide endpoints (`tests/Feature/Main/Portal/AreaGuide`) | 62 tests / 875 assertions passed | | Shared media (`AreaGuideMediaTest` + the `tests/Feature/Common` media selection) | 23 / 128 and 42 / 239 passed | | Catalogue/project-detail regressions (`tests/Feature/Property`, `CatalogueDetailTest`) | 218 / 1072 with 2 pre-existing failures; 12 / 325 passed | | Frontend (Area Guide, project detail, manage pages, `ShowTabs`, composables) | 66 files / 951 tests passed; whole `vitest` suite 190 of 194 files, with 4 pre-existing failing files | | Guards: migration constants, suite links, `pint`, `php -l`, diff whitespace | Passed; the bare `/manage` ratchet is unchanged at 71 | No browser journey, no `npm run build`, no production or master migration or write, no representative assets and no physical device were part of this checkpoint. Five pre-existing test failures were deliberately left alone (catalogue merge concurrency, catalogue combine review tabs, Markets seeding, a missing local `dompdf`, a WhatsApp flow case) plus the portal lesson-staleness guard; the validation record names each one and why. Actual browser acceptance used installed Chrome through Playwright, local authentication, real Mapbox, real catalogue reads and synthetic media. Desktop width was 1440 pixels; narrow layout was 390 pixels using software graphics, not a physical phone. - A labelled 20 by 60 by 20 metre box model uploaded, rendered, saved heading/elevation/scale, and opened real Binastra Cochrane Overview by mesh click. Drag did not select. Closing preserved camera/address state. Publishing exposed the model on the direct reader Guide; the hidden tab button remained absent. - A labelled 2048 by 1024 panorama accepted a manually drawn four-point building polygon, saved the catalogue binding, survived reload and opened Overview by interior click. Selecting the polygon in fullscreen exited fullscreen before opening the drawer. - A labelled six-second, 640 by 360 video and cover uploaded. Native play, seeking to about 4.56 seconds, fullscreen entry and narrow-layout playback passed. - Model, panorama and video test assets were removed. Local row/file checks recorded cleanup. The three private authentication fixture files and their referenced local sessions were removed; the handover contains no reusable login credentials. These checks do not prove every paid/lazy analytical tab's live behavior, physical mobile performance, the user's original panorama quality or surveyed model alignment. Complete-tab reuse/isolation has automated coverage; the live drawer acceptance exercised Overview. Video keyboard Escape exit was not verified; fullscreen entry was. Local test conditions included Mapbox loading failures, an unavailable Reverb connection, an avatar blocked by Chrome and an intermittent bootstrap error: `Unable to boot ApiServiceProvider, configure an API domain or prefix`. The startup error was not diagnosed/fixed by this module. Build changes also triggered an Inertia 409 version reload. Final panorama/video harnesses suppressed only Vite HMR (Hot Module Replacement) notifications; HTTP, media, authentication and rendering remained real. Do not claim a clean application-wide console or production reliability. Ignored local reproduction material is under `storage/app/area-guide-checks/`, including the isolated test configuration, scripts, logs and `browser/` screenshots/state records. Useful logs: `map-http-final.log`, `frontend-final-serial.log`, `suite-test-cached-final.log`, `build-map-final.log`, `build-client-marker-final.log`. `browser/final-local-cleanup.json` records the final counts. This directory also contains private environment backups: do not attach the whole directory or expose its contents. These artifacts are machine-local and may be absent in another checkout. ### 8. What remains and what the next session should do | Remaining work | What is needed / acceptance | |---|---| | Production cutover | Review the existing runbook, actual target endpoint and table-scoped schema/runtime grants. Configure common private cloud storage and deploy the same code. The current read-only master credential cannot do these writes. | | Real two-site acceptance | Edit on site A and reload site B; verify the same revision, replacement/unpublish propagation, differing visibility, conflicting edits and cleanup with independently running workers/caches. | | Representative assets | Obtain actual self-contained models, original complete panoramas and representative videos. Verify alignment, dimensions, file limits, memory, upload/proxy timeouts and replacement failures. | | Physical devices | Exercise maps, models, panorama boundaries, detail drawer, video seeking/fullscreen and repeated open/close on actual target phones. | | Later countries | New map/media country profiles are data-driven. Complete Hong Kong/UAE detail drawers need explicit country adapters and validation; existing country learning/analysis assumptions need their own work. | | Optional later scope | Member panorama/video pages, automatic building segmentation, transcoding and push updates are not delivered first-release capabilities. Do not add them silently. (Per-building basemap clipping under an uploaded model was delivered 2026-09-15 as an automatic rectangle clip.) | | Activity tracking — ONE module, later (user decision 2026-09-15) | The user wants video watch progress and every other reader action in the Area Guide recorded, but explicitly said to build it once, as one module, after the guide's functions are complete. Nothing is recorded today. Hook points: the `