# Area Guide (Main · User Portal) **Portal:** Main · **Routes:** `main.portal.courses.index` (`GET /property/academy?tab=area-guide`; `GET /area-guide` and `GET /area-guide/{area}` redirect there) · `main.portal.area-guide.narration` (`GET /property/academy/area-guide/narration/{area}/{locale}/{chapter}`) · `main.portal.area-guide.chapter-image` · `main.portal.area-guide.chat` (`POST /property/academy/area-guide/chat`) · `main.portal.area-guide.activity` (`POST /property/academy/area-guide/activity`) · **Nav:** "Learning Hub" → **Area Guide** — **in the tab strip since 2026-09-18** (hidden from 2026-09-13 while the section was admin-only). `Lms/Index.vue` binds the tab's `hidden` to the server's `areaGuide.hidden`, so the button shows unless the section lock is showing THIS reader the coming-soon panel; `ShowTabs` resolves `?tab=area-guide` and lazy-mounts the body either way, so `/area-guide/{area}`, tutorial back links and road hand-offs keep working. What the reader gets INSIDE is narrowed separately by the one-area pin (below). Navigation visibility does not bypass the locks · **Gated by:** `['auth','main','contact.verified']` + TEMPORARY admin-only lock, TrainingAccess and membership Function access (in `CoursesController::areaGuideState()`); the narration, chat, walk-station and walk-visit endpoints carry `feature:area-guide` **and apply that same combination themselves** through `AreaGuideViewerAccess::allowsGuide()` (2026-09-14) > **It is a TAB, not a page (2026-08-27), and a HIDDEN one (2026-09-13).** The > guide moved into the [Learning Hub](/docs/modules_handbook/main/lms/readMe.md): > "where should I buy" is reference material a member READS before a course > about it, not a tool they operate, and every other portal nav entry at that > level is a tool. It is registered **fourth** in `Lms/Index.vue`'s `tabs` > (after "How to Use PropertyLab", DMAIC 之路 and 案例复盘) with `hidden: true`, so it has **no > button on the strip** and is reached only through `?tab=area-guide` — an Area > Tutorial back link, the DMAIC road's hand-off, or a copied guide URL. Remove > `hidden: true` to restore the button. What moved is only the chrome — the > guide itself is > [AreaGuidePanel.vue](/resources/js/Components/AreaGuide/AreaGuidePanel.vue), > mounted by [Lms/Index.vue](/resources/js/Pages/Main/Portal/Lms/Index.vue). > `ShowTabs` lazy-mounts the active tab, so a reader who never opens the tab > still downloads neither three.js nor Mapbox. > > **The tab owns its query params (2026-09-14).** It declares > `queryParams: ['country', 'region', 'area']`, and `ShowTabs` deletes exactly > those when the reader leaves the tab — the pair to `AreaGuidePanel.syncUrl`, > which writes them. Without it, a URL copied from e-Learning still carried the > guide's position. Three consequences: params the tab does not own survive (an > unrelated `utm=` is kept), a param the INCOMING tab also declares is kept, and > a reader who leaves the guide and comes back inside the same history entry > lands on the default country/region rather than where they were, because the > deep link the panel re-reads at setup is gone. ## What it does **Registry and catalogue map reader (2026-09-13):** countries, regions and areas are read through the [shared Area Guide registry](/docs/modules_handbook/shared/project-catalogue/area-guide-registry/readMe.md). The authorized reader can additionally enable catalogue project markers, uploaded model placements and map-media viewers through `AREA_GUIDE_MAP_ENABLED`. Project details reuse the complete MY detail surface in a drawer. This does not activate the feature or migrate the real master by itself; rollout and remaining acceptance checks belong to the [catalogue map requirements checklist](/docs/modules_handbook/main/area-guide/catalogue-map-requirements.md). An interactive map of the markets we sell in, where every area carries the story we tell buyers: a tagline, a two-paragraph investment story, labelled facts (rail, drivers, tenants, stock) and a positioning badge (Prime / Hot / Mature / Emerging / Watchlist). **Malaysia** (2026-09-13, PR #149) is the migrated country: KL & Selangor's twelve areas — KLCC, Bukit Bintang, Cochrane, Maluri, TRX, Bangsar, Bangsar South, Old Klang Road, Mont Kiara, Petaling Jaya, Subang Jaya, Cyberjaya — on ONE continuous Mapbox map, in **English or Chinese**, each area narrating itself in a pre-rendered voice **a chapter at a time**, with videos hanging on the map at the places they were shot and a **chatbot** that answers questions about the neighbourhood. Penang and Johor are `soon` shells. An area with a [walkable session](/docs/modules_handbook/main/area-guide/walkable-session/readMe.md) (Cochrane) offers **Walk this area**; an area with published [Area Tutorials](/docs/modules_handbook/manage/area-tutorials/readMe.md) lists its corridor drives. **When catalogue map mode is disabled, Hong Kong and the UAE** (Dubai + Abu Dhabi) keep the original illustrated rendering: **country → region → area**, an illustrated low-poly world (three.js) for the first two levels and the **real pitched street map** (Mapbox Standard: true building heights, roads, street names) inside an area. Their content now also comes from the active registry; this does not add Malaysian narration or chat capabilities to those countries. > **Two guides in one panel, on purpose.** Proving the new map on one country > keeps it a reviewable change instead of a rewrite of three at once. The > split is visible in [AreaGuidePanel.vue](/resources/js/Components/AreaGuide/AreaGuidePanel.vue), > which renders [MalaysiaGuide.vue](/resources/js/Components/AreaGuide/MalaysiaGuide.vue) > for Malaysia and its own three-level flow for the other two. Newly authored > countries can use the continuous street renderer without requiring a new > illustrated geometry asset; the registry's map profile selects the renderer. > When `areaGuide.mapEnabled` is true, every country uses the existing generic > continuous renderer so the catalogue layer has a real Mapbox map to attach to. > Each layer uses that registry country's explicit `iso2`; a missing code never > falls back to MY. This does not add MY chat or narration to another country. > > **The rule, exactly, is `AreaGuidePanel`'s `isContinuous`:** a country gets the > continuous renderer when `mapEnabled` is on, OR its map profile names the > `street` / `continuous` renderer, OR its asset is `westMalaysia`, OR it has no > painted `lands` at all. Only a country WITH painted lands, while the catalogue > map is OFF, falls to the illustrated `AreaMap3d` + `AreaStreetMap` flow — Hong > Kong and the UAE in the legacy content. **The class names are historical:** > `MalaysiaGuide` / `MalaysiaMap` are the generic continuous renderer, not > Malaysia's alone. > **Working on this module locally?** The guide's content lives in the shared > master database, so a developer machine either READS production (no edits > possible — the account is SELECT-only) or edits an isolated local copy. Which > switches, how to pull production's content down, and why its media can be > blank locally with nothing in any log: > [registry handbook → Working on the Area Guide locally](/docs/modules_handbook/shared/project-catalogue/area-guide-registry/readMe.md#working-on-the-area-guide-locally-2026-09-18) > and > [map handbook → Getting production's media onto a development machine](/docs/modules_handbook/shared/project-catalogue/area-guide-map/readMe.md#getting-productions-media-onto-a-development-machine-2026-09-18). > **OPEN TO MEMBERS 2026-09-18** (`AREA_GUIDE_LOCKED=false` on production), > with the tab in the strip and the guide **TEMPORARILY PINNED TO ONE AREA**. > > **The one-area pin.** `AREA_GUIDE_PINNED_AREA=bangsar-south` (config > `area_guide_content.pinned_area` → the `pinnedArea` prop → `AreaGuidePanel`) > opens the guide on that area and hides everything that would take the reader > off it: the **country switcher**, the **language toggle**, the **region > chips** and both **"All areas"** ways back (`MalaysiaGuide`'s `pinned` prop, > whose `closeArea()` becomes a no-op). A URL naming another country or area is > overruled by the pin, since a deep link would otherwise be the way out. > The reason is content, not policy: only Bangsar South has published map > content, and a guide whose other areas open onto an empty map reads as broken > rather than new. **DELETE the env line (+ `config:cache`) and the guide is > whole again** — nothing is hidden from the registry and no story is touched. > A key that is not a live area is IGNORED and the guide behaves normally, so a > typo cannot strand a reader on a page with no navigation. > > *(The alternative — hiding the other areas from the registry itself with > `area-guide:show-only`, see the > [registry handbook](/docs/modules_handbook/shared/project-catalogue/area-guide-registry/readMe.md) > — was deliberately NOT used: it would also take those areas' written stories > and narration away from the admin editor, and this is meant to be temporary.)* > > **The assistant switch.** `AREA_GUIDE_CHAT_ENABLED=false` (config > `area_guide_content.chat_enabled`) turns the per-area "Ask about …" box off > for everyone. Temporary for the same reason as the pin: the answers are only > as good as the area copy, and most areas are still being written. > Two halves, and BOTH are required — `CoursesController::areaGuideState()` > sends an EMPTY `chatAreas` list so the panel never offers the box, and > `AreaGuideController::chat()` `abort_unless`es on the same config so a reader > who kept the URL is refused. A control taken off a page is not a feature > turned off, and every answer here spends the **company** AI key. > Unset means ON. Only a recognised false value turns it off — this project's > `env()` is CakePHP's, so the STRING `"false"` is truthy and a naive cast would > silently leave the assistant on (`filter_var(..., FILTER_NULL_ON_FAILURE)`). > ⚠️ phpunit boots `.env`, so both this and `AREA_GUIDE_PINNED_AREA` are pinned > in `phpunit.xml` beside `AREA_GUIDE_LOCKED` — a developer whose own `.env` > carries the operational value would otherwise turn a dozen chat and gate > assertions into failures (and, the other way round, into tautologies). > > One thing is held back for good until the policy changes: > **360° panoramas stay administrator-only** — that > is the asset's own `audience` (decision D4), not this flag, so no reader > route serves one whatever the section lock says. A member gets the map (3D > models and location videos), the area stories, narration, > the AI questions (unless the assistant switch above is off), > the walkable sessions and the Area Tutorials. > > **The lock below STAYS in the code as an operational kill switch.** It was > written to be deleted when the section opened; it is kept instead because > this section's content is edited live and shared across sites, and one env > line plus a `config:cache` takes it back off members without a deploy. The > "remove it for good" list at the end of this block is still accurate if that > day comes. > > **The lockdown, as it works.** While the flag is on the section is > admin-preview only: an admin sees the real guide plus an amber banner (with a > "Preview what members see" link), a member gets the coming-soon panel. It > was a copy of the Analyze Property lock — a self-contained middleware — until > the guide became a tab: **a tab has no path of its own for middleware to > match**, and a path-matching lock would have taken the whole Learning Hub > with it, so the same three rules now live in > `CoursesController::areaGuideState()` and reach the page as the `areaGuide` > prop (`locked` · `hidden` · `previewUrl` · `exitUrl` · `mapboxToken` · `mapEnabled` · > `gameAreas` · `chatAreas` · `countries` · `malaysia` · `narration` — map credentials, > capabilities and full content are withheld when locked: a locked > reader gets neither the map nor the stories). > > **`hidden` is the tab BUTTON's own flag (2026-09-18), separate from `locked`.** > Only the section lock hides the button — while the guide is being written > there is nothing to advertise. A trainee's Day-2 lock and the membership gate > keep the button, because each of those panels names a door the reader can walk > through themselves; hiding them would leave a member with no idea the section > exists. An admin sees the button even while the section is locked, with the > banner. The tab stays reachable by URL either way. It still hangs off > `features.area_guide_locked` (`AREA_GUIDE_LOCKED`, default **true**; phpunit > forces it off so the suite exercises the real guide), and opening the > section is `AREA_GUIDE_LOCKED=false` — no deploy. > > **Why `=false` is safe here, and only here (2026-09-14).** `env()` in this > codebase is CakePHP's and hands back the RAW STRING, so a plain `(bool)` cast > reads `"false"` as TRUE — the trap that used to leave this section locked > while the `.env` said it was open. `config/features.php` now parses the value > (`filter_var(..., FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE)`), so > **`false` / `0` / `off` / `no` / an empty value all open it, an UNSET flag > keeps it locked, and anything unrecognised fails CLOSED.** Its neighbour > `ANALYZE_PROPERTY_LOCKED` is deliberately NOT changed with it and still > requires `=0`: re-parsing that one would OPEN any environment already > carrying the ineffective `=false`. Do not generalise this rule to it. > > **The lock is authorization, not a withheld prop (2026-09-14).** It used to > live only in `areaGuideState()`, which meant a member who knew the URLs could > still call the reader endpoints directly — chat in particular, spending the > company AI key. The narration, chat, walk-station and walk-visit endpoints, > and the Area Tutorial player, now each call > [`AreaGuideViewerAccess::allowsGuide()`](/src/AreaGuide/Support/AreaGuideViewerAccess.php) > — the same three rules, server-side — and answer **403**; chat returns it in > the panel's own `{answer: null, error: …}` shape. The map, asset and media > routes call `allows()`, which is that plus the catalogue-map capability. The > Learning Hub also withholds the **Area Tutorial cards** from a locked reader, > since those cards name the guide's areas and drives. > > ⚠️ **Deploy note.** With `AREA_GUIDE_LOCKED` unset or true a plain member gets > 403 from those endpoints instead of being served — that is the point of the > flag. Production runs it `=false` since 2026-09-18. `=false` only works > because the value is parsed (above); an env edit needs `config:cache` where > config is cached. > > **Before opening it anywhere, check what a member would actually get:** > `php artisan tinker scripts/area-guide-reader-check.php` prints the four > gates (the section lock, the content source, the map capability, the > membership matrix) and then the registry's areas and the published assets > split by audience — so "the matrix is set to selected memberships with none > chosen" and "every panorama is admin-only, and the models are still drafts" > are visible before a member finds them. Read-only. > > To remove the lock for good, delete: `areaGuideState()`'s lock branch in > [CoursesController.php](/app/Http/Controllers/Main/Portal/CoursesController.php) > (keeping the props it builds), the `area_guide_locked` branch in > [AreaGuideViewerAccess.php](/src/AreaGuide/Support/AreaGuideViewerAccess.php) > (keeping the trainee and Function-access checks — they are not temporary), > [AreaGuideComingSoon.vue](/resources/js/Components/AreaGuide/AreaGuideComingSoon.vue), > [AreaGuideLockBanner.vue](/resources/js/Components/AreaGuide/AreaGuideLockBanner.vue) > (+ both mounts in [Lms/Index.vue](/resources/js/Pages/Main/Portal/Lms/Index.vue)), > [AreaGuideLockdownTest.php](/tests/Feature/Main/Portal/AreaGuide/AreaGuideLockdownTest.php), > the `area_guide_locked` entry in [config/features.php](/config/features.php), > and the `AREA_GUIDE_LOCKED` lines in `.env.example` / `phpunit.xml`. > **Sub-module:** [Walkable Session](/docs/modules_handbook/main/area-guide/walkable-session/readMe.md) > — an area you WALK instead of read (2026-09-08). A 3D avatar on the area's > real street map, with the developments that really stand there as beacons: > walk up to one and it opens its live catalogue figures, a question derived > from those figures, and the reading to take away. Cochrane first; an area is > switched on in the active registry (`config/area_guide_game.php` in legacy mode), and its stations are > whatever the project catalogue says stands in the circle. On Malaysia's > continuous map the walk is a view the reader steps into (**Walk this area** > on the map card); on the illustrated guide the avatar is simply on the > street map. > **Area Tutorials (2026-08-30).** An area's story can also list guided **corridor drives** — an > animated Mapbox route that stops at each condo with its live Subsale Database figures, chaptered > to the team's walkthrough video. That is a separate, database-backed module with an admin builder: > [Area Tutorials](/docs/modules_handbook/manage/area-tutorials/readMe.md). This panel only renders > the "Drive the area" list (the `tutorials` prop, published tutorials keyed by `area_key`) and links > to `/property/academy/area-tutorials/{uuid}`. Its admin picks the area from the registry below. > **A locked reader is sent none of them** (the cards name the guide's areas and drives), and the > player at that URL applies `allowsGuide()` too. The hub casts the map to an object, so an empty > one ships as `{}` rather than `[]` — the page declares the prop as an Object, and an empty PHP > array is now the common case. That shape cannot be pinned with `assertInertia`, which decodes the > payload to a PHP array where the two are indistinguishable; the guard reads the raw Inertia JSON. ## How it works — shared registry (Phase 1) - **One selected source.** [AreaGuideRegistry](/src/AreaGuide/Services/AreaGuideRegistry.php) exposes `countries($full)`, `country($key)`, `findArea($key)`, `walkableAreas()` and `source()`. `AREA_GUIDE_CONTENT_SOURCE=legacy` is the default and preserves the versioned import baseline plus Malaysia's PHP copy. After an explicit import, `database` reads active countries, regions and areas from the selected content database. There is no automatic import or fallback on a missing table, an empty result, a connection failure or an invalid database configuration. - **Global ownership, with an explicit local development workspace.** [config/area_guide_content.php](/config/area_guide_content.php) selects `AREA_GUIDE_CONTENT_CONNECTION=catalogue` by default. Outside local/testing, the connection guard requires the same host, port and database as the configured live master; a site's copied catalogue cannot silently become a private registry. Local/testing may explicitly choose `area_guide_local`, a separate loopback database named by `AREA_GUIDE_LOCAL_DATABASE`. This lets developers edit local Area content while their catalogue project connection remains read-only. It is a development workspace, not a second production source. - **Admin authoring.** Manage → Portal → **Area Guide** (`GET /manage/area-guide`, `manage.area-guide.index`) lists the hierarchy. `POST {type}`, `PUT {type}/{id}` and `DELETE {type}/{id}` under that prefix manage countries, regions and areas. Viewing requires an admin and `view-area-guide`; writing also requires `manage-area-guide`, database source mode and `AREA_GUIDE_CONTENT_EDITING=true`. Import, immutable keys, revisions, archive rules and actor provenance belong to the [registry handbook](/docs/modules_handbook/shared/project-catalogue/area-guide-registry/readMe.md). - **Full content is authorized page data.** `CoursesController::areaGuideState()` sends `countries`, the compatibility `malaysia` prop (regions still keyed by slug), `gameAreas`, `chatAreas`, `source` and `unavailable`. Existing global, trainee and membership locks are evaluated before full content is read. A shared-source failure clears countries, stories, capabilities and the Mapbox token and sets `unavailable=true`; the rest of the Learning Hub remains available. - **Selectors get a smaller contract.** On authenticated academy, road, Area Tutorial and Area Guide admin routes, `HandleInertiaRequests` shares `areaGuideSource` and lazy `areaGuideCountries = countries(false)`: names, keys, coordinates and map metadata, without stories. Unrelated routes receive neither prop. Database failure returns an authoritative `[]`. [useAreaGuideRegistry](/resources/js/composables/useAreaGuideRegistry.js) supplies the tutorial selectors/labels and road handoffs; the panel receives the authorized full payload. Any supplied array, including `[]`, wins over bundled content. Static frontend fallback is allowed only for legacy/older unversioned hosts when that array is absent, never for database mode. - **Rendering assets stay in code.** The database stores map profile/asset keys; [registry.js](/resources/js/utils/areaGuide/registry.js) resolves versioned geometry and translated copy. Existing Malaysian, Hong Kong and UAE renderers remain; new country pins can use the generic continuous street map. This is not uploaded building-model support. Deep links resolve the active registry's keys, including newly authored areas; `soon` regions do not resolve to an open area. - **Three panel states, not two (2026-09-14).** `areaGuideState()` sends `unavailable` when the shared guide content could not be read, and the same catch also empties `countries`. `Lms/Index.vue` forwards it to `AreaGuidePanel`, which renders a FIRST branch ahead of the empty-registry one: `[data-area-guide-unavailable]` — *"Area Guide is temporarily unavailable."* That is deliberately distinct from the empty-`countries` *"Area Guide is not available right now."*: one is a passing fault that is expected back, the other is a guide with nothing published. Until now the flag was sent and dropped, so an outage read to the member as a new install. - **Capability and ownership boundaries remain explicit.** Chat and narration consume `country('malaysia')`; `chatAreas` exposes only Malaysian keys outside `soon` regions, so a new country does not show a chat control that cannot answer. **One class decides that set:** [`MalaysianGuideAreas`](/src/AreaGuide/Support/MalaysianGuideAreas.php) — the registry's own `findArea()` rule (skip `soon` regions) narrowed to Malaysia — and the hub's `chatAreas` prop, `ChatRequest`'s `area` rule, the narration route and `area-guide:narrate` all read it, so the keys one of them accepts are exactly the keys the others do. An area under a `soon` region is a 422 from chat and a 404 from narration, with no AI call spent. Walkable worlds come from `walkableAreas()`. Tutorials/stops, learner visits and narration `media` rows remain on their original site database; this phase shares the area identity/copy, not those records or audio files. Shared narration media ownership is still pending. ## How it works — catalogue map reader - **Capability:** `CoursesController::areaGuideState()` sends `mapEnabled` only when the Guide's existing locks allow access, the registry is available and `area_guide_content.map_enabled` is true. `Lms/Index.vue` forwards it without changing the hidden navigation tab. Backend map/media routes enforce their own authorization; changing a frontend prop does not grant access. - **One real map:** `AreaGuidePanel` passes the active country through `MalaysiaGuide` to `MalaysiaMap`. After Mapbox's `load`, a `shallowRef` passes the actual map to `CatalogueMapLayer`, with the registry's explicit ISO2 country code. The layer reads the bounded viewport from `GET /property/academy/area-guide/map`; published new-project and subsale memberships share the same project markers. The map uses Mercator projection for uploaded model coordinates. The layer removes listeners, markers and custom layers before its parent calls `map.remove()` in `onUnmounted`. - **Complete project details:** a project marker or uploaded model emits its descriptor to `AreaGuidePanel`, which opens `ProjectDrawer`. The MY drawer uses the [shared Project Detail content](/docs/modules_handbook/shared/project-detail/readMe.md) and canonical page payload, including all existing tabs. HK/AE still use their standalone detail pages until their distinct payload/request adapters exist. Project selection and drawer tab/unit changes do not mutate the Guide's URL or map camera. - **The drawer is a real modal, and its failures are told apart (2026-09-14).** It carries `role="dialog"` + `aria-modal="true"` with a Tab/Shift+Tab wrap and a `focusin` listener that pulls back focus landing on the page beneath; anything CONTAINED BY or FOLLOWING the panel counts as a higher layer, so a nested dialog (the hero lightbox) stays reachable and owns its own Escape. Three failure kinds, because "Try again" on a permanent failure is a lie: **transient** (network / 5xx) is the only one that offers a retry; **gone** (404, uuid mismatch, no detail URL) offers nothing; **standalone** (a non-MY country's 422, an unknown adapter) offers an **"Open project page"** new-tab link built from the 422 body's own `href`, falling back to the map feed's `href`, and passed through a same-origin guard so a `//host/…` value in a response body is refused outright rather than rendered. - **A card inside the drawer opens a NEW TAB.** The Developer Record and New Supply cards render as plain `` when the content is in the drawer, never as an Inertia `` — following one in place would replace the Learning Hub underneath and lose the reader's area, map camera and the drawer itself. The standalone project page is unchanged and still uses ``. - **A PANORAMA LEAVES THE PAGE (2026-09-18, user).** Selecting a camera marker no longer opens the reader's modal — it opens `GET /property/academy/area-guide/panoramas/{uuid}?from=…` (`main.portal.area-guide.panorama`) in a NEW TAB, rendering the SAME Inertia component the admin's `manage.area-guide.panoramas.show` renders. A 360° photograph in a modal beside the story was a few hundred pixels of a sphere with a close button over it. One component, so the viewer, the flights between panoramas, the building markers and the little-planet intro cannot drift between the two audiences; everything that used to be tested on the panel side now lives in `Pages/Manage/AreaGuide/Panorama.test.js`. - **The reader route hands the page `canManage: false` and `reader: true`.** `canManage` alone could not carry it — an administrator on the MANAGE page also has it false whenever editing is off for the site, and would then lose the note that says so. `reader` decides two things and no more: which detail endpoint the building drawer calls (the reader's `/property/academy/area-guide/map/buildings/{uuid}`, never a manage URL its middleware would refuse), and that the admin-facing "editing is disabled" note is not shown to someone who was never offered editing. - **The gate is `authorizeAsset()`'s, unchanged**, so a panorama's `audience` still decides. Every panorama is `AUDIENCE_ADMIN` today (decision D4), so in practice the page serves an administrator browsing the reader's guide; a guide-audience panorama would reach a member through the same route with nothing to change, and a DRAFT still reaches nobody but an admin. - ⚠️ **`?from=` is an open-redirect surface and is checked server-side.** The tab has no history to go back through, so the page is TOLD where Back goes. Only a same-site path is accepted: an absolute URL, a scheme-relative `//host`, a `javascript:` scheme, a backslash (which a browser reads as a slash) and any control character all fall back to the guide rather than being cleaned up and followed. The link itself is opened with `noopener`. - A **video** marker still opens the modal: it is a rectangle, and a rectangle beside the story is what it wants to be. - **Map media:** selecting a video first requests `GET /property/academy/area-guide/map/assets/{uuid}`. The viewport response does not include building markers; only the authorized detail response is passed to `AssetViewer`. (For panoramas the same endpoints now serve the standalone page above rather than the modal.) A panorama's building marker (a click-placed ring with the building's name, `area_guide_hotspots` — the traced outlines were retired 2026-09-15) returns EITHER a project UUID, which becomes the canonical project-detail request URL and opens the same drawer, OR a custom-building UUID (a tower that is not a catalogue project, introduced by an admin with free-form tabs of rich text — see the [map handbook](/docs/modules_handbook/shared/project-catalogue/area-guide-map/readMe.md)), which opens `BuildingDrawer` from `GET /property/academy/area-guide/map/buildings/{uuid}` over the still-open viewer. A panorama may also carry arrow hotspots to other panoramas; clicking one flies there inside the same viewer (`AreaGuidePanel::flyToAsset` fetches the destination's asset JSON and swaps `selectedAsset` without unmounting `AssetViewer`), and readers only receive arrows whose destination is published on this site and whose position an admin has confirmed (an automatic return arrow stays hidden until then). A panorama's third marker kind (2026-09-15) opens a location VIDEO — the same video asset a map pin plays: the viewer re-emits it as `select-video` and `AreaGuidePanel::openVideo()` reads it from the same authorized asset endpoint into a SECOND `AssetViewer` stacked over the panorama, exactly as `BuildingDrawer` stacks, so closing the video returns the reader to the view they were standing in. Members have no standalone video page (nor panorama page) yet; an admin gets the full-screen video page in a new tab instead. Readers never receive a marker whose video is still a draft. A 3D building model on the map opens what it stands for: the project drawer for a catalogue project, or `BuildingDrawer` (`select-building` → `openBuilding`) for a custom building that is not a catalogue project — the same building record a panorama marker can link, so one write serves both places. A panorama opens with a "little planet" intro and flies between linked panoramas with a blur-and-crossfade, never a black screen; linked images are preloaded so the switch is quick. Media image/video delivery retains its endpoint's audience checks, including administrator-only panoramas. Switching country, closing the viewer, choosing another media marker or disabling the capability cancels the previous asset request and ignores late responses. - **Existing learning flows:** area selection, narration, chat capability, walk stations/questions, tutorial links and their existing storage ownership remain in their current components. Catalogue map overlays are additional map content; they do not replace station questions or corridor tutorials. - **Validation:** focused frontend tests cover enabled/disabled wiring, explicit country, real-map readiness, child-before-map cleanup, marker loading, stale responses and project drawer events. Existing Guide URL and walk tests remain in the verification set. This does not claim browser, real-asset or production acceptance. ## How it works — Malaysia - **One map, no levels.** [MalaysiaMap.vue](/resources/js/Components/AreaGuide/MalaysiaMap.vue) is a single Mapbox Standard instance. Our ILLUSTRATION is drawn on top of it: an opaque teal sea, the West Malaysia states as `fill-extrusion` slabs painted in a colour from their flag (`fill-extrusion-vertical-gradient` shades the side walls, which is what makes them read as extruded), and their names. All of it fades out between **z7.6 and z9.4**; the Klang Valley districts fade in from **z8.2** and the landmark pins from **z8.8**. Below that the reader is simply on the real map, with real building heights — Exchange 106 and the Twin Towers stand on their own footprints. **Those zoom constants ARE the feature** and are named at the top of the component. There is no level to be on, so there is nothing to switch. - **Why three.js could not do this.** It has no tiles and no detail levels, so there is no zoom at which its scene can dissolve into real streets. "One continuous map" and "three.js at the top" cannot both be true. The trade was the low-poly charm, bought back with the painted sea and the flag-coloured slabs. - **Still ONE `new Map()` per visit.** Mapbox meters a map load per instantiation, not per zoom or pan. The map is created once and flown around for the rest of the visit; every area click is a `flyTo`. Switching to Hong Kong unmounts it (the PR's own choice — the two guides swap with `v-if`), so a reader who flips countries repeatedly does pay a load per flip. - **Content comes from the active registry, in BOTH languages**, and reaches the tab inside the `areaGuide` prop (`areaGuide.malaysia`). It moved out of JS the day the chatbot was added: the model's dossier must be assembled on the SERVER, or a reader could tell it what to believe about an area before asking a question. `config/area_guide.php` supplies that copy only in legacy mode; database mode uses the authored records. Both languages travel in the same payload, so the toggle is free — no reload, no second request, and the reader keeps their place on the map. Geometry stays in [geoMalaysia.js](/resources/js/utils/areaGuide/geoMalaysia.js). The registry side of Malaysia (`malaysia.js`) is explained in its own section below. - **Narration is PRE-RENDERED, never synthesised on view.** `php artisan area-guide:narrate` reads the active registry's Malaysian areas, then walks every area × EN/ZH through [GeminiTtsClient](/app/Helpers/GeminiTtsClient.php) and stores the audio via `MediaService` under the `area-narration` collection, tagged `meta: {area, locale}`. The tab reads them back through [AreaNarration.php](/app/Support/AreaNarration.php) as `areaGuide.narration` — `{area: ['en', 'zh']}`, WHICH areas are voiced, never a URL: a signed GCS URL lives 15 minutes and this tab is built for long dwell, so the URL is minted per play by `AreaGuideController@narration` (a redirect to a fresh signed URL, 404 when the area has no audio; **403** for a reader the lock holds back — the audio IS the story the lock withholds). **What is read aloud is the tagline and then the story paragraphs. The labelled facts are NOT read** — a list read out ("Landmark, colon, Exchange 106") is what a screen reader does, not someone showing you a neighbourhood. The command renders only areas the tab actually serves (`MalaysianGuideAreas`), so an area under a `soon` region is skipped unless `--include-soon` asks for it — the flag exists for rendering ahead of a region going live. **A row whose bucket object has gone is NOT a 404.** Signing does not check that the object still exists, so the player is redirected to storage, which then refuses it; recover with `area-guide:narrate --area= --force`. The URL is null, and the route 404s, only when SIGNING itself fails. **Nothing is written back into source** — the media row IS the record, so re-rendering an area is not a commit and not a merge conflict. Re-runnable: an area that already has audio is skipped unless `--force`, which stores the replacement successfully before deleting the old media (file AND row). These remain site-local, ownerless `Media` rows tagged by area key and locale. A registry failure stops the command before any synthesis; playback returns 503 when the registry is unavailable and 404 for an unknown area or absent audio. It **autoplays** when an area is opened, which is a deliberate exception: opening an area is a click, on a guide that promises to talk you through the neighbourhood. Three things keep that honest — a browser that blocks autoplay is not fought (the button is the gesture it wanted), pressing **pause** turns autoplay off for the rest of the visit (`sessionStorage`), and **leaving the landmark stops it** — as does stepping into the walk. - **The chatbot is grounded and bounded.** `POST /property/academy/area-guide/chat` → `AreaGuideController@chat`, under `AiRequest::PROMPT_AREA_GUIDE_CHAT` ([resources/prompts/area_guide_chat.md](/resources/prompts/area_guide_chat.md)). The browser sends an area KEY and a question, never the copy; the controller builds the dossier from the active registry's Malaysian copy. The prompt lets it use general knowledge freely and **forbids stating any price, psf, yield, rental figure, or a foreign-ownership / MM2H / stamp-duty rule** — those go to an agent, because they go stale, differ per project and nationality, and a foreign buyer will quote them back at us. It runs on the **COMPANY key**, so the limits are the whole budget: `throttle:12,1` on the route for the burst and `DAILY_QUESTIONS = 60` per user in the controller for the bill. **The reader gate comes before all of that (2026-09-14):** `ChatRequest::authorize()` calls `AreaGuideViewerAccess::allowsGuide()`, which Laravel runs BEFORE the rules, so a refused reader never reaches the registry, never reaches the rate limiter and never spends a call; `failedAuthorization()` returns the panel's own `{answer: null, error: …}` shape at 403, and the controller repeats the check for any caller that skips the Form Request. A provider outage returns 503 with the same error shape, never a 500. The thread is not persisted (a conversation table here has its own privacy story) and clears when the reader opens another area. - *(Phase 1 gave every area one optional YouTube field. That field is **retired** — see "THE AREA'S OWN VIDEO BOX IS RETIRED" below. A video now hangs on the map marker for the place it was shot at.)* - **The country view has a target on it.** A continuous map lost what the old country LEVEL was good at: three clickable regions telling an arriving reader where to go. Region pins are back (one live, two `soon`), shown BELOW the landmark-pin threshold so the two sets hand over with never both or neither on screen. Clicking one flies past the crossfade to z9.7, where the districts and landmark pins have already appeared. - **The camera orbits a landmark, and only a landmark.** Opening one flies down and then turns; the turn never starts during the descent. It belongs to the landmark, not the page: below **z13.4** there are no 3D buildings to turn around, and more than ~4km off-centre is leaving rather than adjusting, so both end it — and both restore **north**, because a country at a stranger's bearing is a reader with no compass. Any gesture stops it dead and it resumes 3.5s after they stop, easing the pitch back first so the same shot returns. Two traps: `originalEvent` is what distinguishes a person's gesture from our own camera moves (without it the orbit stops itself on frame one), and the release is bound to raw `mousedown`/`touchstart`/`wheel` rather than Mapbox's `dragstart`, which only fires past a drag threshold — until then a per-frame `setBearing` fights the drag handler and panning appears broken. - **Labels are placed, not averaged.** A state's name goes at the point furthest from any edge of its largest landmass, not its centroid: Terengganu is a strip and Selangor wraps Kuala Lumpur, so the average of either is not in the middle of it. Two states carry a `label_at` override because their REGION PIN sits on the same spot (Selangor's natural point is 4px from the KL pin at country zoom). Kuala Lumpur is an `enclave` and has no label until the districts. - **Place labels are OFF below z9.** Mapbox Standard renders them above every slot an added layer can reach, so they cannot be painted over — the sea covered Thailand's land and left Hat Yai's name in the water. They come back with the real map, where town names are how a stranger orients. - **The walk is a second view of the same area.** The walkable session needs [AreaStreetMap.vue](/resources/js/Components/AreaGuide/AreaStreetMap.vue) — the avatar is a custom layer of that map — and two Mapbox maps cannot share the screen. So for an area in `gameAreas`, MalaysiaGuide fetches the stations as it opens (through [useAreaWalk](/resources/js/composables/useAreaWalk.js), the same composable the illustrated guide uses) and, once they are in, shows **Walk this area · N stops** on the map card. The button mounts the street map OVER the continuous one (kept with `v-show` afterwards — a remount is a billed map load) with the HUD and the station card on top, and is the way back. The narration is stopped on the way in. The area's story and chat stay where they were. - **A change of LANGUAGE is not a change of place (2026-09-14).** Toggling EN/中文 re-localizes the open area into a NEW object with the same key, and every watcher that used to treat that as a new place did something visible and wrong: re-flying the camera, stopping the orbit, rebuilding every marker, dropping the open station card and refetching the stations mid-walk. All of them are now keyed on the KEY — `activeArea?.key`, and for the pin lists a `pinShape()` digest (key, lat, lng, zoom, face/emoji/icon, soon) that deliberately EXCLUDES names — with a `relabel()` pass that writes the new language onto the existing pin buttons in place. A region pin whose CAMERA actually changed is still rebuilt, because its click handler closes over the object it was built from. `useAreaWalk` watches the key for the same reason, so a reader mid-walk stays mid-walk. - **The toggle resets to English when it disappears.** It is gated by `hasTranslations` — any country, region or area with Chinese copy — so a reader who chose 中文 and then switched to a country without it was left with Chinese chrome and Chinese basemap labels over English content and **no control to switch back**. A watch on `hasTranslations` now sets `locale` back to `en` at exactly that moment. - **The map camera is validated before Mapbox sees it (2026-09-14).** `countryMapProfile()` in [registry.js](/resources/js/utils/areaGuide/registry.js) clamps the authored `map` profile with the same rules the Manage editor's canvas uses: centre to ±180 / ±85, zoom and minZoom to 0–22 with zoom floored at minZoom, pitch 0–85, bearing ±360, and `bounds` required to be a 2×2 finite array in range **with sw < ne on both axes** — Mapbox does not reject inverted bounds, it builds a nonsense `maxBounds`. A malformed field falls back to the camera derived from the country's own pins; an explicit `bounds: null` still means "no limit". Matching the editor is the point: the server's Form Request does not validate bounds ORDERING, so before this the reader and the editor could disagree about the same saved profile. A country saved with no centre or zoom at all is normal — the reader frames it from its region and area pins. - **Two camera fixes and one stacking fix, all from the same reading pass.** (a) A region-pin click sets a one-flush `regionFlightPending` so its own flight survives the panel closing the open area in answer; the `activeArea` watcher skips `resetView()` for exactly that flush, and closing an area any other way still returns to the country view. (b) A `?region=`-only deep link — and a region picked while the map was still loading — now flies to the region instead of leaving the camera on the country (`startOnRegion` plus an internal `regionPickedBeforeLoad`); note the link must name `?country=` too, since `resolveDeepLink` ignores a bare `?region=`. (c) `giveUp()` now REMOVES an abandoned `Map`, so a watchdog timeout or a pre-load error no longer leaves a billed map loading into a detached node until the tab changes. - **The walk view is on top, and the catalogue panel gets out of its way.** `MalaysiaMap` takes a `covered` prop (true while the walk is up) and passes it to `CatalogueMapLayer` as `panelHidden`, which `v-show`s the info/toggle box away so its checkboxes are unreachable too — the feed, markers and models keep running underneath. The walk overlay also moved to `z-30` inside an `isolate` container, so the map's own layers stack inside that box rather than against the page. Together they stop the catalogue toggles painting over `AreaStreetMap`'s bottom-left *"Click anywhere to walk there"* hint. Accepted cost: the feed's error line and Retry are hidden with the panel, so a feed failure during a walk is silent until the reader leaves the walk. - **The URL and the deep link are the panel's, not the guide's.** The open area is AreaGuidePanel's `areaKey` (MalaysiaGuide receives it as `area` and emits `update:area`), so `?country=malaysia®ion=kl-selangor&area=cochrane`, `/area-guide/cochrane` and the DMAIC road's hand-off all work the same way for every country — see the URL bullet under Hong Kong and the UAE. Malaysia has no region level, so its live region (KL & Selangor) is simply written as open. - **Failure is loud, never blank.** No token, a CDN refused by an ad blocker, a request black-holed (12s watchdog), a revoked / over-quota token (`error` before first paint) all end at the same notice, and the areas and their stories still open from the list. There is no three.js fallback for Malaysia: its content and geometry no longer match what `AreaMap3d` expects. - **One screen, and only the prose gives way.** Both columns are exactly the viewport's height, so nothing is left over to become white space — which is what a sticky map produced, a sticky element shorter than its row leaving the rest of that row empty. - **THE STORY OWNS THE RIGHT COLUMN** (2026-09-19, user). It used to sit in a short scroller UNDER the map, and that made it read as a **caption**: a few lines of grey text with a picture above them taking the eye. The reading is the point — the map is what the reading MOVES — so the story now gets a full-height column of its own (pictures, prose, the rail, the voice) and the map gets the whole of the other one. The corridor drives and the **chat** sit below it, the chat still taking every pixel after everything else because it is the one element whose useful height is not fixed. **Nothing about the scroll → camera path changed with the move**, which is why the move cost nothing: whichever chapter is nearest the middle of the scroller is still the one the map has flown to, and the rail still jumps by scrolling. The one visible consequence is that **the rail turned horizontal**: down the side of a short box it read as an index, across the top of a tall column it reads as progress through a story, which is what it is. - **THE STORY IS CHAPTERS, AND SCROLLING THEM DRIVES THE MAP** (2026-09-18, user: "make it very very interactive to elaborate the story OF THE AREA"). One paragraph IS one chapter. The map stays put above a short scroller, and whichever chapter is nearest the MIDDLE of that scroller is the one the map has flown to; the current chapter is set darker and larger while the rest fade back, and a vertical rail of dots says how long the story is and jumps. - **One paragraph per chapter is the whole contract.** The reader's `story` is per-locale, the cameras in `profile.chapters` are not, and they meet on the INDEX — no second structure to fall out of step. A locale with fewer paragraphs simply has fewer chapters, never a padded one with no words. - **A chapter with no `center` does not move the map.** That is what makes a story that is only prose behave exactly as it did before this existed, with no migration: today's two-paragraph areas became two cameraless chapters. - **Nearest-to-the-centre, NOT `IntersectionObserver`** ([useStoryChapters.js](/resources/js/composables/useStoryChapters.js)). IO answers "is this inside the root by more than N%", which in a scroller a few hundred pixels tall is true for two chapters at once for most of the scroll — so the answer flickers between them at exactly the moment the map would be flying. Nearest-to-the-centre has one answer at every scroll position by construction. Measured on `requestAnimationFrame`, because a trackpad fires scroll far faster than the screen refreshes and the map is the expensive consumer. - ⚠️ **Two edge cases that are load-bearing.** The LAST chapter can never reach the middle of a scroller it does not fill, so at the bottom of the scroll the last chapter IS the answer — but that rule is guarded on the box having a height and something to scroll, because an unlaid-out scroller reports 0 for both and `0 + 0 >= -2` is true: without the guard the story opens on its LAST chapter for one frame and the map jumps to the end of the area before the reader has read a word. - The rail JUMPS by scrolling, never by flying directly. The scroll is the only path to the camera, so the rail and a hand cannot disagree. - ⚠️ **A jump lands on the chapter's TOP, and used to CENTRE it** (fixed 2026-09-19, user: "the view is no good… make sure the chapter view is start from the top"). Centring computes `offsetTop - (boxHeight - chapterHeight)/2`, which was fine while a chapter was a paragraph — and wrong the moment chapters gained pictures, because a chapter with a picture is TALLER than this short scroller, so that term goes negative and the jump overshoots by half the overflow. Every auto-advance landed on a cropped picture and a paragraph starting mid-sentence. A chapter is a scene that begins with its picture; you start it at the beginning. - ⚠️ **THE READING LINE MOVED TO THE TOP, and that is the other half of the same fix.** Top-aligned jumps broke the old "nearest the middle of the viewport" rule outright: a chapter is ~330px tall in a ~700px column, so the centre line sits 350px down — already PAST the chapter the jump had just arrived at. Every auto-advance therefore **skipped a chapter**: its voice never played, the rail moved two, and the map flew somewhere nobody had read about (user: "when the chapter 1 is ended, it direct turn to chapter 2"). `readingLine()` now puts it `min(96px, 40% of the box)` below the top, which is also just what reading is — you start at the top and work down. - **A constant, not a fraction**, because chapters differ enormously: one with a picture is ~330px and one that is four lines of prose is ~110px. Any proportional line generous enough for the tall one overshoots the short one completely — the same bug again, for the chapters with no pictures. - `measure()` asks **containment first** (the chapter the line is inside), falling back to nearest for the gaps between chapters and the space at either end. Chapters do not overlap, so at most one can contain a point: the single-answer property that made this worth choosing over `IntersectionObserver` is intact. - The **bottom-of-scroll** rule is separate and still correct — and it is why a regression test for this needs SIX chapters. With three, the scroll bottoms out before the second jump and that rule answers instead, hiding the bug. - ⚠️⚠️ **`offsetTop` IS NOT MEASURED FROM THE SCROLLER, and this was the real one.** It is measured from `offsetParent` — the nearest POSITIONED ancestor — and nothing between a chapter and the page is positioned: not the scroller, not the story card, not the column, not the grid. So every `offsetTop` came back inflated by the page header, the card's padding, the title row and the player. In `measure()` the damage was **invisible**, because the same inflation sits in both the value compared and the `scrollTop` just set from it — the two errors cancelled and the rail named the right chapter. On screen it was not invisible at all: `scrollTo` fed that inflated number straight to the browser, so the view landed a whole header lower than the chapter it claimed to be showing (user: "chapter 2 is … But it turn to chapter 3"). `geometry()` takes a rect difference against the scroller instead, which has no such assumption — and is immune to the next person adding `relative` to any wrapper. **The fixtures model the trap:** `layOut()` stubs `getBoundingClientRect` AND an `offsetTop` inflated by a `chrome` argument, so anything that goes back to reading `offsetTop` fails the test the same way it fails on screen rather than quietly reading a zero. - **THE VOICE READS A CHAPTER AND THEN TURNS THE PAGE** (2026-09-19, user: "AI voice that reads the chapters and auto-advances"). Narration is rendered **one audio file per chapter**, not one per area, and a chapter finishing SCROLLS to the next one — which is what moves the map, the rail and the next audio. One path, so the voice and a reader's own scrolling can never disagree; at the last chapter it simply stops rather than looping. - **Why per-chapter, and not a single file with timestamps.** One long file cannot say where one chapter ends and the next begins, so the voice could never be the thing that advances the story — which is the whole feature. - It **reuses the existing pipeline unchanged** (user's choice): still pre-rendered by `area-guide:narrate` into GCS through `MediaService`, still ownerless media keyed by `meta`, still nothing written back into the content. `meta` simply gained a `chapter`, and `chapters()` returns index => text preserving the ORIGINAL indexes so a skipped paragraph cannot shift the rest. - ⚠️ **If the render fails with an HTTP error from Google, check the KEY first.** `GeminiTtsClient` read `.env` only until 2026-09-19 and ignored the key saved on Manage → AI Providers — so the page said *Verified / Connected* while the voice sent an empty key. Fixed (it resolves the UI key first now, like every other Gemini consumer), and pinned by `GeminiTtsClientTest`; the full story is in the [AI handbook](/docs/modules_handbook/shared/ai/readMe.md)'s text-to-speech section. - ⚠️ **Old whole-area audio is deliberately invisible, not remapped.** `AreaNarration::available()` skips any row without an integer `chapter` rather than treating it as chapter 0, because it reads the OLD script — the one that opened with the `tagline` this guide no longer has. Re-render with `area-guide:narrate --area= --force` and it returns as real chapters. **Nothing detects stale audio**: an edited story keeps the old voice until someone runs that command. - `available()` now returns `{area: {locale: [chapterIndexes]}}`, and the panel offers a play button **only for a chapter the server actually has** — a chapter with no audio falls silent rather than 404ing at the reader. This is also why **nothing appears at all on a machine with no rendered narration**: the control is absent, not broken. Run `area-guide:narrate` to get one. - **It moved into the story column and became a PLAYER, not a button** (2026-09-19, user). It used to be a bare circle beside the area's name in the map's header — which was where the story used to be too, so when the story moved the control was left a column away from the words it reads. It now sits between the story's title and its prose, and carries a **track** (where the voice is, to the pixel — a ring around a 36px button could only answer that to within about a fifth), the **elapsed / total time**, a **status line** naming the chapter, and **four bars that move** while it speaks. The bars and the track are `aria-hidden`; everything they convey is said in words by the status line, and `prefers-reduced-motion` stops the motion while keeping both. - ⚠️ **This is why the story block is mounted with `v-show`, never `v-if`.** The player's `