Documentation

Overview

MapStay helps boutique hotels draw building outlines and room shapes, link PMS inventory, set upcharges, and embed an isometric map on the booking path. Your workspace syncs to Supabase when you sign in; the editor also keeps a local copy for fast undo and offline edits.

• Layout: building footprint, walls, doors, and outdoor pathways.
• Rooms: top-nav inventory: categories, upcharges, and floorplan assignment status.
• Floorplan → Rooms: trace guest room polygons and drag inventory onto shapes.
• Amenities: service zones (stairs, pool, gym, etc.) that power walk routing on the guest map.

The floorplan editor uses a workflow nav across the top (Layout → Rooms → Amenities → Preview) and places canvas tools in a bottom-center toolbar so the drawing surface stays clear on tablet and desktop.

Account & brand

When you create an account you set a company or hotel name (your brand). That name becomes a URL slug used in all public guest links. Google sign-up collects the brand on a short onboarding step before you create your first property.

You can change the brand later under Settings → Account after signing in. Each property then has its own slug under that brand, e.g. /harborview-hotels/harbor-inn.

Units: toggle metric or imperial under Account settings or in the floorplan editor toolbar. The same preference is used for wall dimensions, property settings, and distance labels on the guest preview and booking widget.

Floors & blueprint

Each property has ordered floors. New floors copy the closed building outline from the floor below. Editing a floor marks it customized; the same outline propagates upward to floors that have not been customized yet, never downward.

Upload a blueprint image and adjust opacity. Calibrate scale by double-clicking a wall or entering width/height in the side panel. Set map north with the compass control.

Undo and redo (toolbar or ⌘Z) keep up to 20 steps per floor in browser storage, including after refresh.

Layout, walls & doors

The Layout tool draws one closed building outline per floor. Use Walls to add interior partitions. Doors snap to wall segments; enclosed amenities need a door on their boundary so the guest router can reach them.

Pathways connect outdoor areas (pool decks, parking, gardens). Walk routes prefer pathway centerlines over shortcuts across open ground.

Rooms & inventory

Open Rooms from the top navigation to manage your full inventory: room categories (with PMS photos when connected), upcharges, and whether each room is assigned on a floorplan shape.

Rooms are grouped by category with a photo header. Each room appears as a compact card showing name, upcharge, and assigned / unassigned. Click a card to edit details in the sidebar: description, photos, and category.

On desktop you can drag cards between categories. On phone, use Move to different category on a card instead. Floorplan assignment still happens in the editor. Open a room in the sidebar and use Trace on floorplan (desktop/tablet only).

In the floorplan Rooms tool, trace closed polygons and drag inventory from the side panel onto shapes. Canvas labels use the inventory display name, not raw PMS reference codes.

Moving a room shape translates the whole polygon. Corners snap to the building and neighboring rooms without warping angles.

Supported PMS connectors: Cloudbeds and Mews (Settings → Connect PMS). Once rooms are traced and assigned, they appear on the guest map preview.

Phone vs tablet

On a phone-sized screen you can use the property dashboard, the top-nav Rooms inventory page, and light account/property settings. Floorplan editing, the booking widget customizer, and PMS connection require a tablet or desktop.

If you open a desktop-only page on a phone, you will see a short message asking you to switch to a larger device. Navigation links to those areas are hidden on phone so the experience stays focused.

Amenities

In the Amenities tool, click corners to draw closed zones. Drag a type from the catalog onto a zone, or onto an existing guest room to convert that room into the amenity.

Stairs, elevators, and escalators enable cross-floor routing. Pool, gym, lobby, and other types appear as destinations on the guest map when reachable from the selected room.

Guest URLs

Public guest pages use your brand slug and property slug:

/{company-slug}/{property-slug}

Example: /harborview-hotels/harbor-inn. Set the property slug under Settings → Property after signing in. Legacy /guest/… URLs redirect to the new format when possible.

Map & walk times

Preview widget in the floorplan editor opens the same isometric map guests see. Route distances follow your metric/imperial preference; walk durations are always shown in minutes.

Under Property settings you can tune:

• Property color: room highlights and route styling.
• Amenity zone colors: semantic (pool blue, garden green), brand tint, or a custom tint.
• Walking speed multiplier: higher values mean faster walking and shorter estimated minutes (1.0 = average, 1.15 = slightly faster). Distances are unchanged.

Get embed

Open Get embed from the property dashboard to add MapStay to your site. Choose a placement (link, button, or search bar), customize accent and theme, then copy the link or snippet. Every placement uses the same guest widget path. /{company}/{property}.

Technical reference

Stack

• Next.js App Router, CSS Modules, Supabase auth + workspace sync
• Types: src/types/database.ts, store: src/lib/store/types.ts
• Geometry: src/lib/geometry/ (snap, pathfinding, isometric)
• Guest scene: src/lib/guest/buildGuestScene.ts

Key routes

• /[companySlug]/[propertySlug]: public guest widget
• /dashboard/properties/[propertyId]/floorplans/[floorplanId]/layout
• …/rooms, …/amenities, …/preview
• /api/pms/reservation-hold: checkout hold stub

Editor state

FloorplanEditorProvider wraps the canvas; mutations go through updateFloorplan. Per-floor undo history persists under spatial-floor-history-{floorplanId} in localStorage.