Tour App

The Tour app is a guest-facing interactive experience designed for layout visitors. It runs on tablets or phones at your layout and lets guests explore different areas, trigger sound and lighting effects, watch videos, and learn about the technical implementation -- all without needing operator-level access.

Home Hub

The home page serves as a central hub for the tour experience. It welcomes visitors to the layout (Tamarack Junction in the default configuration) with a logo carousel and a brief description of what guests can do.

Below the welcome banner, a grid of tour cards provides entry points into each section of the app:

Each card has a hover animation and a themed background pattern. Only enabled cards are displayed to guests. The Drive Trains card is currently disabled in the default configuration.

A Layout Status card at the bottom shows whether the app is connected to a layout, displaying the layout ID when connected or a warning when not.

Welcome Page

The Welcome page provides the starting point for first-time visitors. It is divided into two columns:

Left Column -- Introduction

• Introduction Video -- An embedded video player with the layout overview video (e.g., "Adventure Awaits at Tamarack Junction").
• Feature List -- A summary of what visitors can do:
  • Control interactive effects (lights, sounds, animations)
  • Explore layout areas with detailed videos and explanations
  • Technical deep dives into electronics and automation
  • Audio commentary on construction techniques

Right Column -- Quick Navigation

• Area Selection -- A grid of cards for each layout area. Clicking an area navigates to its detail page. The default areas include:

  • Tamarack Station (marked as Recommended)
  • Roseberry Yard
  • Payette Subdivision
  • Deadman's Curve
  • Round Valley
  • Thunder City
  • Eagle Nest
  • Tripod Peak

• Layout Stats -- Key numbers about the physical layout:

  • Scale: HO (1:87)
  • Track Length: ~200 feet
  • Interactive Effects: 12 available
  • Layout Areas: 8 sections

Effects Control

The Effects Control page (/effects) presents a grid of guest-accessible effects. Each effect is rendered as a GuestEffectCard component with a toggle button that guests can press to activate or deactivate the effect.

Effects are loaded from Firestore using the useEfx().getGuestEffects() composable from @repo/modules. Only effects marked as guest-accessible appear in this view.

The grid uses auto-animate transitions for smooth entry and exit when the effect list changes. Effects are categorized by type (lighting, sound, animation, relay) and some have auto-timeout behavior -- for example, the Grade Crossing Bell automatically deactivates after 10 seconds, and the Mountain Echo Horn after 8 seconds.

Media Library

The Media Library (/media) provides a browsable collection of videos and audio content organized by layout area. The page uses a three-column layout:

Left Sidebar -- Filters

Three dropdown selectors let guests narrow the media collection:

• Layout Area -- Filter by area (Tamarack Station, Thunder City, Eagle Nest, etc.).
• Content Type -- Filter by video or audio.
• Category -- Filter by introduction, area detail, technical, or overview.

Below the filters, a Quick Access panel provides one-click buttons for Introduction, Technical Details, and Layout Overview content.

Main Content -- Media Cards

The filtered results display as a responsive grid of media cards. Each card shows:

• A thumbnail image (or placeholder).
• The media title and description.
• Duration and content type badge.
• A play button to open the media player.

Player Dialog

Clicking a play button opens a modal dialog with the media player. The dialog supports both video and audio playback with standard controls. URL query parameters (e.g., /media?filter=technical) allow the page to pre-filter content on load, so the Technical Details tour card on the home page jumps directly to technical content.

Explore Sections

The Explore Sections page (/sections) presents the layout areas as a grid of section cards. Each card includes:

• A thumbnail image with a play overlay on hover.
• The section name and a short description.
• Category chips (Intro, Technical).
• A View Details button to navigate to the full area detail page.
• A play button to open a quick preview of the section's intro media in a dialog.

The default sections are:

• Tamarack Station -- Main passenger station with platforms, signals, and station activities.
• Thunder City -- Urban district with city sounds, street lights, and animated signs.
• Eagle Nest & Payette Canyon -- High mountain vistas and canyon operations with scenic trestles.
• Payette Subdivision -- Rural mainline with crossings, bridges, and long scenic runs.
• Roseberry Yard and Industrial Auto Park -- Busy freight yard and switching operations.

Area Detail

Navigating to /area/:id opens the full detail page for a specific layout area. The page uses a two-column layout:

Left Column (Wide)

• Featured Media -- A media player placeholder with the area's featured video or audio content and a play button.
• Construction Details -- Two-column panel showing physical construction specs (platform length, building count, track length, etc.) alongside technical feature chips (Working Signals, DCC Block Detection, Scenic Lighting, etc.).
• Interactive Effects -- A grid of GuestEffectCard components for effects that belong to this area. Guests can activate effects directly from the area page.

Right Column (Narrow)

• Related Media -- A list of all media items associated with the area, each with a play button for quick access.
• Navigation -- Quick links to the Effects Control page, the full Media Library, and the Home page.
• Area Statistics -- Summary counts for media items, interactive effects, and construction time.

Areas in the default Tamarack Junction layout include both overview entries and dedicated technical entries (e.g., "Tamarack Station" and "Tamarack Station (Technical)"), so visitors can choose between scenic tours and deeper technical content.

Authentication

The Tour app supports two authentication modes:

• Firebase Auth -- Full Firebase user authentication for registered users.
• Guest Auth -- Lightweight guest access using the requireGuestOrAuth route guard. Guests do not need an account; the useGuestStore Pinia store tracks their session.
• Demo Mode -- When VITE_DEMO_MODE=true is set, authentication guards are bypassed entirely, allowing unrestricted access for demonstrations.

The login page (/login) is rendered by the TourLogin component and supports both authentication paths.

Running the Tour App

Start the Tour app in development mode:

pnpm --filter=deja-tour dev

The app runs on its default Vite port (3031) and requires a Firebase connection for effects data and layout information.