Premium AI Template (Technical)

The Premium AI Template is a comprehensive signage template for kiosk and companion with a unified design (glassmorphism, light), 3D wayfinding, highlights (curated content), AI search, and concierge. This section describes the technical structure for developers and editorial staff.

Template ID and Slugs

• Template ID (internal): ai-premium
• Companion Slug (URL): premium – the NOW! app is loaded at /companion/t/premium.
• Registry: The signage app maps the template ID to the companion slug; handoff URLs and redirects use this mapping.

Variant "AI Wayfinding" (same base)

• Template ID: ai-wayfinding – Kiosk Route: /ai-wayfinding – uses the same AIPremiumKioskShell and the same data pipeline as AI Premium.
• Dashboard: Own entries in signageTemplateOptions['ai-wayfinding'] (kiosk and companion options, same field structure as AI Premium).
• Companion Slug: centerplan → /companion/t/centerplan (same companion shell; options from ai-wayfinding).
• DOOH: 16:9 playlist always under the header (with configured idle playlist); fullscreen idle off by default after inactivity, can be activated in the kiosk options (see DOOH Mode in Kiosk).
• AI Wayfinding (Minimal Layout): AI Search and bottom menu are off by default; a compact handoff QR remains visible in the bottom right. Everything can be reactivated in the kiosk options (feature toggles).
• Wayfinding Display: Default Light (kioskColorScheme: light); optional Dark in the kiosk options. In Dark mode: Header with clock, date, optional weather (Open-Meteo at coordinates in the center) and city; DOOH as a rounded 16:9 block under the header; dark map area; Zoom +/− (white circles) and wayfinding pill; floor round; bar "Hot picks"; note "Tap area for details." In Light mode, the wayfinding layout (pills, pill-button, rounded DOOH) remains, colors as in the light premium kiosk.

If you operate a new center with this template, you select "Premium AI" (or the corresponding name) in the dashboard under Digital Signage / Kiosk. The companion is then accessible under the same template skin.

Shells and Screens

Kiosk

• Shell: AIPremiumKioskShell – controls navigation, idle timeout, DOOH slots, overlays (handoff QR, group session QR, accessibility). Landscape: The template is optimized for landscape kiosks (more compact bottom bar, adjusted chip positions, more map area).
• Screens: Home (KioskHome), Shop Detail (KioskShopDetail), Wayfinding (KioskWayfinding), if applicable search and detail views. The home page offers highlights as two centered badge rows directly under the center plan (split about evenly per row from the center; optional tile “All Highlights” for slide-up), with info icon/tooltip for explanation. Above or in the same bar: optional AI Search. Quick links (shops, gastronomy, services, news/offers) in 4 columns, wayfinding, and the buttons "Continue on phone," "Invite Companion" (group mode), and "Nearby." Shops, gastronomy, and services grids as well as "Nearby" are visually implemented as maps (4 per row).
• Data: Is fetched when loading the kiosk URL from the dashboard (or via the signage API): shops, hot picks (displayed as highlights), featured news, services, center config. The same data sources are used by the companion.

Companion (NOW! App)

• Shell: AIPremiumCompanionShell – reads URL parameters (centerId, sessionKey, handoffTargetShop, joinCode), initializes session tracking, and passes data to the companion home.
• Main View: CompanionHome – fullscreen center plan (3D or 2D depending on configuration), highlights (with info tooltip for curated content), concierge chat bar, header with logo, “NOW!”, parking, group, and menu as floating glass pills (without a continuous white bar); in inline route, this header is hidden.
• Further Views: Wayfinding (CompanionWayfinding), offers/events via menu or navigation. "Show on map" and "Start route" from the concierge minimize the chat and highlight the goal on the plan (no switch to a separate wayfinding page).
• Handoff from Kiosk: When scanning the "Continue on phone" QR, the user lands on the companion homepage (not a separate center plan subpage), since the plan is already visible there.

Configuration and Data Flow

• Center: centerId determines which center is loaded (subdomain or parameter).
• Preloaded: Hot picks (UI: highlights), shops, news/events, services, center info (name, logo, accent color), wayfinding data (floors, SVG/3D).
• Concierge: Uses the dashboard API (visitor chatbot); the signage app forwards requests via proxy to avoid CORS from the dashboard. Context (shops, offers, parking, trending, return policies, etc.) is loaded server-side from the AI context library.
• Handoff: Session is created via POST /api/qr-sessions (signage); the handoff URL contains sessionKey, centerId, and optionally shop/screen. The QR leads to /companion/t/premium?…. In the premium AI template, screen=companion-home is set so that the user lands on the homepage (with map).
• Group Mode ("Invite Companion"): A group is created via POST /api/group-session (signage proxy to the dashboard). The overlay explains the process in three steps (You are here → Companion scans → Done) and prominently highlights the QR code and code alternative.
• DOOH / Idle: After the expiration of inactivity, the kiosk area is softly resized and the DOOH slot with playlist is displayed. The playlist loops. A clear hint ("Tap – Reactivate kiosk" / "Fullscreen map, shops & routes appear again") clarifies that a tap restores the full kiosk UI.
• Local Hero (DOOH): In the dashboard under Digital Experience → DOOH, still maintainable; the kiosk no longer shows a local-hero bar ("With us in the center") above or beside the DOOH slot – only the configured advertising playlist remains.

Newly Added: Modular Kiosk Features (Dashboard)

In the Digital Experience → Kiosk → Premium AI Options section, additional feature toggles have been added. This allows each center to roll out the template leaner or more extensive without code adjustments.

Feature Toggles (per Center)

• Premium Modules: enableOffers, enableFood, enableServices, enableHighlights, enableNearby, enableGroupSession, enableA11y, enableHandoffQr, enableDoohIdle
• New Base Modules (default off): enableTraffic, enableSocialFeed, enableTransitMonitor
• Alternative Labels for Quicklinks: offersLabel, shopsLabel, foodLabel, servicesLabel, trafficLabel, socialFeedLabel, transitMonitorLabel

Base Modules (new)

• Traffic: Google Maps embed (traffic situation) via trafficMapEmbedUrl
• Social Feed: Elfsight/iframe source via socialFeedEmbedCode (src is extracted)
• Public Transport Monitor: Departure monitor/embed via transitMonitorEmbedUrl

All three modules appear as additional icons in the quick links and open a unified slide-up (KioskEmbedSlideUp).

Shared Wayfinding Package

The 3D map, SVG routes, and associated logic come from the Shared Package @mall-os/wayfinding (Monorepo: packages/wayfinding). This package is the central source for all apps and templates:

• Digital Signage (this template, kiosk/companion) uses it for the 3D view, route parsing, and optionally the find-route API (types FindRouteRequest/FindRouteResponse).
• Center Website uses it for the wayfinding page and center plan embeds (e.g., Goldbeck, HBB).
• New kiosk/companion or website templates should only integrate this package; no duplicates in the apps. See packages/wayfinding/README.md for integration and exports.

v0 / own signage frontends (kiosk touch zones)

If you build kiosk, totem, or companion interfaces with v0: Kiosk → Part H (Touch Zones); Companion/NOW! → Part I (mobile, handoff QR) — always H + I together. Center plan: Part F + F2. Copy-Paste: v0 + Cockpit — Part H & I.

Routes in the Dashboard and in the 3D View

• Dashboard (Center Plans → Floor → "Routes" tab): With the "Draw Route" mode (R) you click waypoints one after the other (e.g., entrance → shop). Each click generates a connection (WaypointConnection) in the database. These connections appear as lines in the 2D overlay of the route editor. After creating a connection, the data reloads to ensure lines are reliably displayed.
• Auto-Snap for Editors: When setting waypoints, the editor can automatically snap points to the SVG routing grid (#routes/#Routes). This reduces "zigzag" connections and makes maintenance significantly easier without external tools.
• Accessibility QA Layer: In the route editor, a filter can highlight only accessible connections (without stairs/escalator, without wheelchairAccess=false) for quick quality control.
• Wayfinding Route Source (Option): Under kiosk options → wayfinding, the route source can be selected: Auto (default: dashboard route if a kiosk location is assigned, otherwise SVG), Only SVG Routes (#routes/#Routes layer in the SVG), or Only Route Editor (only waypoints from the dashboard). This allows specifically avoiding simultaneous or conflicting use of SVG routes and dashboard routes.
• 3D View (Kiosk/Companion): The drawn route is used in the 3D map as soon as the route source is "Dashboard" or "Auto" and the kiosk is assigned to a Display Location (Digital Experience → Hardware → "Location (Display)"). Then the route is calculated from the database graph (WaypointConnection) via the find-route API. With Only SVG Routes, only the SVG group "#routes" (or "#Routes") is used.
• Accessible Routing in Kiosk: The routing API considers mode-dependent avoidStairs, preferElevator, and accessibilityRequirements (e.g., wheelchair/stroller mode) to ensure the route is correctly adjusted in the kiosk.

Newly Added: Slide-ups and Detail Views (UI/UX)

The kiosk slide-ups for shops, gastronomy, services, news, offers, highlights, nearby have been revised:

• harmonized spacing/padding logic for header, filter, content, and detail areas
• modern grid presentation with up to 5 cards per row (especially landscape/XL)
• additional filters (search, floor, category) including hit display and reset
• improved detail views with existing dashboard data (e.g., opening hours, phone, website, description)
• better portrait/landscape balance for touch operation in kiosk operation

Design and Theme

• Theme: Light (no dark mode); glassmorphism and subtle skeuomorphism, uniform for kiosk and companion.
• Design Tokens: Central values (colors, spacings, shadows) are located in a theme file (e.g., ai-premium-theme.ts); header, cards, and chat bar use the same styles.
• Safe Area: Header and lower areas consider env(safe-area-inset-*) for notch and gesture bar.

AR Navigation and Shopfront Recognition (Beta)

The companion offers, in addition to the classic 2D/3D map view, an AR Mode (Beta) that uses the smartphone's camera:

AR Navigation (Dead Reckoning + Image Tracking)

• Plan/AR Toggle: In the wayfinding view (CompanionWayfinding), the user can switch between Plan (3D map) and AR (camera live image with direction arrow).
• Dead Reckoning: Gyroscope (heading) + accelerometer (step counter) estimate position and direction. The estimate is projected onto the known corridor graph via Map Matching to compensate for sensor drift.
• Position Calibration: Initial position comes from the QR scan at the kiosk. Additionally, shopfront images can serve as image markers (see below) to automatically calibrate the position while on the move.
• Drift Warning: After a certain number of steps, the system warns and offers a rescan (QR or shopfront).

Shopfront Recognition (MindAR.js Image Tracking)

• Technology: MindAR.js – browser-based image tracking with WebGL and TensorFlow.js. No native app required.
• Workflow:
  1. Dashboard: For each waypoint (shop/location), a shopfront image (photo of the shopfront) can be stored as arMarkerImageUrl – in the existing position JSON field, no schema change.
  2. Dashboard: The “AR Marker” button in the route editor compiles all shopfront images on a floor client-side into a .mind file (MindAR format).
  3. Companion: When opening the AR mode, the app loads the .mind file and the image targets via /api/ar/image-targets.
  4. Live: The user points the camera at a shopfront → MindAR recognizes the image → AR Overlay displays shop name, offers, news, and events. At the same time, the position for navigation is calibrated.
• Fallback: If no image tracking is available (no .mind file configured), QR-based calibration remains active.

AR Fields in Dashboard (Waypoint Editor)

In the tab Center Plans → Floor → Routes, there is a collapsible panel under each waypoint “AR Navigation (Beta)” with:

Field	Description
Viewing Direction °	Where the user is looking at this location (dropdown: N, NE, E, SE, S, SW, W, NW)
Corridor Direction °	Corridor direction to the next waypoint (degree)
Distance (m)	Distance to the next waypoint in meters
Landmarks	Visible reference points (comma-separated, e.g., “fountain, H&M left”)
Shopfront Image	URL to photo of the shopfront (for MindAR image tracking)

All fields are optional and are stored as additional JSON properties in the existing Waypoint.position field – no data loss, no schema change.

Configuration

• .mind file URL: Is stored in the center options under signageTemplateOptions.arMindFileUrl and passed to AIPremiumCompanionShell in CompanionWayfinding.
• Image Targets: The API /api/ar/image-targets?centerId=... delivers all waypoints with arMarkerImageUrl for a center.

Data Integrity (without data loss)

The new options have been introduced additively:

• new template options are optional and have defaults
• existing data structures remain valid
• AR and additional fields are complemented in existing JSON fields (no destructive schema restructuring)

Important Files (Orientation in Codebase)

• Kiosk Shell: e.g., AIPremiumKioskShell.tsx
• Companion Shell: e.g., AIPremiumCompanionShell.tsx
• Companion Home: e.g., CompanionHome.tsx
• Handoff (platform-wide): HandoffQROverlay, buildHandoffUrl, getHandoffCompanionPath
• Group Session: GroupSessionQROverlay, Signage API /api/group-session
• Concierge UI: CompanionChatbar; Backend: Dashboard Visitor Chatbot + AI Context
• AR Navigation: ARNavigationView.tsx, useARNavigation (Dead Reckoning), useImageTracking (MindAR)
• AR Overlay: ARShopOverlay.tsx (Shop info for recognized shopfront)
• AR Utilities: ar-utils.ts (Position JSON parsing with AR fields)
• MindAR Compiler: mind-ar-compiler.ts (Client-side .mind compilation in dashboard)
• Image Targets API: /api/ar/image-targets (delivers AR marker for a center)

If you create a new template and want to connect the companion, you need: an entry in the signage companion registry (template ID → companion slug), a companion shell that processes sessionKey/handoff/joinCode, and the use of the shared handoff and group overlays. The Premium AI Template serves as a reference.