### Installation Bundle Setup

Source: https://github.com/tomgilder/routemaster/blob/main/example/deep_linking/linux/CMakeLists.txt

Configures the installation process to create a relocatable application bundle. It cleans the bundle directory and sets up paths for data and libraries.

```cmake
# === Installation ===
# By default, "installing" just makes a relocatable bundle in the build
# directory.
set(BUILD_BUNDLE_DIR "${PROJECT_BINARY_DIR}/bundle")
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

# Start with a clean build bundle directory every time.
install(CODE "
  file(REMOVE_RECURSE \"${BUILD_BUNDLE_DIR}/\")
  " COMPONENT Runtime)

set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}/lib")
```

--------------------------------

### Get Dependencies

Source: https://github.com/tomgilder/routemaster/blob/main/CLAUDE.md

Fetch and install project dependencies.

```bash
# Get dependencies
flutter pub get
```

--------------------------------

### Installation Bundle Configuration

Source: https://github.com/tomgilder/routemaster/blob/main/example/book_store/linux/CMakeLists.txt

Sets up the installation prefix to create a relocatable bundle. It ensures a clean build bundle directory on each installation.

```cmake
set(BUILD_BUNDLE_DIR "${PROJECT_BINARY_DIR}/bundle")
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

install(CODE "
  file(REMOVE_RECURSE \"${BUILD_BUNDLE_DIR}/\")
  " COMPONENT Runtime)
```

--------------------------------

### Define Installation Directories

Source: https://github.com/tomgilder/routemaster/blob/main/example/simple_example/linux/CMakeLists.txt

Sets variables for the installation directories for data and libraries within the bundle.

```cmake
set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}/lib")
```

--------------------------------

### Installing Application Components

Source: https://github.com/tomgilder/routemaster/blob/main/example/book_store/linux/CMakeLists.txt

Installs the application executable, ICU data, Flutter library, and bundled plugin libraries to their respective destinations within the installation bundle.

```cmake
set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}/lib")

install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)

foreach(bundled_library ${PLUGIN_BUNDLED_LIBRARIES})
  install(FILES "${bundled_library}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endforeach(bundled_library)
```

--------------------------------

### Install Application Executable

Source: https://github.com/tomgilder/routemaster/blob/main/example/mobile_app/windows/CMakeLists.txt

Installs the main application executable to the specified runtime destination. This makes the application available to be run.

```cmake
install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)
```

--------------------------------

### Define Installation Directories

Source: https://github.com/tomgilder/routemaster/blob/main/example/mobile_app/windows/CMakeLists.txt

Sets variables for the installation directories of the application's data and libraries within the bundle.

```cmake
set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}")
```

--------------------------------

### Install Application Target and Assets

Source: https://github.com/tomgilder/routemaster/blob/main/example/deep_linking/linux/CMakeLists.txt

Installs the application executable, ICU data, Flutter library, and bundled plugin libraries into the designated installation paths within the bundle.

```cmake
install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)

foreach(bundled_library ${PLUGIN_BUNDLED_LIBRARIES})
  install(FILES "${bundled_library}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endforeach(bundled_library)
```

--------------------------------

### Install Application Executable and Data

Source: https://github.com/tomgilder/routemaster/blob/main/example/mobile_app/linux/CMakeLists.txt

Installs the application executable to the bundle's root directory, and installs ICU data and the Flutter library to the data and lib directories within the bundle, respectively. This ensures all necessary components are included.

```cmake
set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}/lib")

install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)
```

--------------------------------

### Basic Routemaster Setup with Tabs

Source: https://github.com/tomgilder/routemaster/blob/main/README.md

This snippet shows the complete routing setup for an app with tabs and pushed routes, including defining routes and initializing the MaterialApp.

```dart
final routes = RouteMap(
  routes: {
    '/': (_) => CupertinoTabPage(
          child: HomePage(),
          paths: ['/feed', '/settings'],
        ),

    '/feed': (_) => MaterialPage(child: FeedPage()),
    '/settings': (_) => MaterialPage(child: SettingsPage()),
    '/feed/profile/:id': (info) => MaterialPage(
      child: ProfilePage(id: info.pathParameters['id'])
    ),
  }
);

void main() {
  runApp(
      MaterialApp.router(
        routerDelegate: RoutemasterDelegate(routesBuilder: (context) => routes),
        routeInformationParser: RoutemasterParser(),
      ),
  );
}
```

--------------------------------

### Run All Tests

Source: https://github.com/tomgilder/routemaster/blob/main/CLAUDE.md

Execute all tests, including integration and example app tests, using a provided script.

```bash
# Run all tests including integration and example app tests
./run-all-tests.sh
```

--------------------------------

### Install Bundled Plugin Libraries

Source: https://github.com/tomgilder/routemaster/blob/main/example/mobile_app/linux/CMakeLists.txt

Iterates through a list of bundled plugin libraries and installs each one to the bundle's lib directory. This ensures that all necessary plugin dependencies are included in the application bundle.

```cmake
foreach(bundled_library ${PLUGIN_BUNDLED_LIBRARIES})
  install(FILES "${bundled_library}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endforeach(bundled_library)
```

--------------------------------

### Install Flutter Library

Source: https://github.com/tomgilder/routemaster/blob/main/example/mobile_app/windows/CMakeLists.txt

Installs the main Flutter library file to the application's library directory. This is a core component for running Flutter applications.

```cmake
install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)
```

--------------------------------

### Set Installation Prefix for Bundled Application

Source: https://github.com/tomgilder/routemaster/blob/main/example/mobile_app/windows/CMakeLists.txt

Configures the installation prefix to be next to the executable, allowing the application to run in place. This is particularly useful for Visual Studio builds.

```cmake
set(BUILD_BUNDLE_DIR "$<TARGET_FILE_DIR:${BINARY_NAME}>")
set(CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD 1)
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()
```

--------------------------------

### Query Parameters Setup

Source: https://github.com/tomgilder/routemaster/wiki/API-Quick-Start

Define routes that accept query parameters. Access parameters via route.queryParameters.

```dart
// Path '/search?query=hello' results in SearchPage(query: 'hello')
RouteMap(routes: {
  '/search': (route) => MaterialPage(
        child: SearchPage(query: route.queryParameters['query']),
      ),
})
```

--------------------------------

### Install Flutter Assets

Source: https://github.com/tomgilder/routemaster/blob/main/example/deep_linking/linux/CMakeLists.txt

Installs the Flutter assets directory into the application bundle, ensuring all necessary assets are included for runtime.

```cmake
# Fully re-copy the assets directory on each build to avoid having stale files
# from a previous install.
set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)
```

--------------------------------

### Clean Build Bundle Directory on Install

Source: https://github.com/tomgilder/routemaster/blob/main/example/simple_example/linux/CMakeLists.txt

Installs a custom command to remove the build bundle directory before installation, ensuring a clean state.

```cmake
install(CODE "
  file(REMOVE_RECURSE \"${BUILD_BUNDLE_DIR}/\")
  " COMPONENT Runtime)
```

--------------------------------

### Configure Installation Prefix for Windows Bundles

Source: https://github.com/tomgilder/routemaster/blob/main/example/navigation_bar/windows/CMakeLists.txt

Sets the installation prefix to be adjacent to the executable for Windows bundles, allowing the application to run in place. This is crucial for Visual Studio integration.

```cmake
set(BUILD_BUNDLE_DIR "$<TARGET_FILE_DIR:${BINARY_NAME}>")
set(CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD 1)
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()
set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}")
```

--------------------------------

### Install AOT Library for Release/Profile Builds

Source: https://github.com/tomgilder/routemaster/blob/main/example/mobile_app/windows/CMakeLists.txt

Installs the Ahead-Of-Time (AOT) compiled library to the data directory, but only for Profile and Release configurations. This is used for performance optimization.

```cmake
install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  CONFIGURATIONS Profile;Release
  COMPONENT Runtime)
```

--------------------------------

### Basic App Routing Setup

Source: https://github.com/tomgilder/routemaster/wiki/API-Quick-Start

Configure MaterialApp.router with RoutemasterDelegate and RoutemasterParser for basic path-to-page mapping.

```dart
MaterialApp.router(
  routerDelegate: RoutemasterDelegate(
    routesBuilder: (context) => RouteMap(routes: {
      '/': (routeData) => MaterialPage(child: PageOne()),
      '/two': (routeData) => MaterialPage(child: PageTwo()),
    }),
  ),
  routeInformationParser: const RoutemasterParser(),
)
```

--------------------------------

### Set Installation Prefix for Bundle

Source: https://github.com/tomgilder/routemaster/blob/main/example/simple_example/linux/CMakeLists.txt

Configures the installation prefix to a bundle directory within the build directory, used for creating relocatable bundles.

```cmake
set(BUILD_BUNDLE_DIR "${PROJECT_BINARY_DIR}/bundle")
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()
```

--------------------------------

### Install Bundled Plugin Libraries

Source: https://github.com/tomgilder/routemaster/blob/main/example/mobile_app/windows/CMakeLists.txt

Installs any bundled libraries required by plugins to the application's library directory. This ensures that plugins have access to their necessary dependencies.

```cmake
if(PLUGIN_BUNDLED_LIBRARIES)
  install(FILES "${PLUGIN_BUNDLED_LIBRARIES}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()
```

--------------------------------

### Path Parameters Setup

Source: https://github.com/tomgilder/routemaster/wiki/API-Quick-Start

Define routes with path parameters using the ':paramName' syntax. Access parameters via route.pathParameters.

```dart
// Path '/products/123' will result in ProductPage(id: '123')
RouteMap(routes: {
  '/products/:id': (route) => MaterialPage(
        child: ProductPage(id: route.pathParameters['id']),
      ),
})
```

--------------------------------

### Installing Flutter Assets

Source: https://github.com/tomgilder/routemaster/blob/main/example/book_store/linux/CMakeLists.txt

Installs the Flutter assets directory into the application bundle. It ensures assets are re-copied on each build to prevent stale files.

```cmake
set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)
```

--------------------------------

### Redirect Route Setup

Source: https://github.com/tomgilder/routemaster/wiki/API-Quick-Start

Set up a route that automatically redirects to another specified route using the Redirect class.

```dart
RouteMap(routes: {
    '/one': (routeData) => MaterialPage(child: PageOne()),
    '/two': (routeData) => Redirect('/one'),
})
```

--------------------------------

### Cupertino Tab Setup

Source: https://github.com/tomgilder/routemaster/wiki/API-Quick-Start

Configure routes for Cupertino-style tab navigation using CupertinoTabPage.

```dart
RouteMap(
  routes: {
    '/': (route) => CupertinoTabPage(
          child: HomePage(),
          paths: ['/feed', '/settings'],
        ),
    '/feed': (route) => MaterialPage(child: FeedPage()),
    '/settings': (route) => MaterialPage(child: SettingsPage()),
  },
)
```

--------------------------------

### Set Installation RPATH

Source: https://github.com/tomgilder/routemaster/blob/main/example/mobile_app/windows/CMakeLists.txt

Configures the runtime search path for libraries. '$ORIGIN/lib' means libraries will be searched for in a 'lib' directory relative to the executable's location.

```cmake
set(CMAKE_INSTALL_RPATH "$ORIGIN/lib")
```

--------------------------------

### Tab Setup

Source: https://github.com/tomgilder/routemaster/wiki/API-Quick-Start

Configure routes for tabbed navigation using TabPage, defining the main tab route and its sub-paths.

```dart
RouteMap(
  routes: {
    '/': (route) => TabPage(
          child: HomePage(),
          paths: ['/feed', '/settings'],
        ),
    '/feed': (route) => MaterialPage(child: FeedPage()),
    '/settings': (route) => MaterialPage(child: SettingsPage()),
  },
)
```

--------------------------------

### Basic App Routing Setup

Source: https://github.com/tomgilder/routemaster/blob/main/README.md

Sets up the basic routing for a Flutter application using RoutemasterDelegate and RoutemasterParser.

```dart
MaterialApp.router(
  routerDelegate: RoutemasterDelegate(
    routesBuilder: (context) => RouteMap(routes: {
      '/': (routeData) => MaterialPage(child: PageOne()),
      '/two': (routeData) => MaterialPage(child: PageTwo()),
    }),
  ),
  routeInformationParser: RoutemasterParser(),
)
```

--------------------------------

### Project Initialization and Basic Settings

Source: https://github.com/tomgilder/routemaster/blob/main/example/mobile_app/linux/CMakeLists.txt

Initializes the CMake project, sets the minimum required version, defines the project name and languages, and configures the executable and application IDs. It also sets modern CMake policies and installation paths for bundled libraries.

```cmake
cmake_minimum_required(VERSION 3.10)
project(runner LANGUAGES CXX)

set(BINARY_NAME "mobile_app")
set(APPLICATION_ID "com.example.mobile_app")

cmake_policy(SET CMP0063 NEW)

set(CMAKE_INSTALL_RPATH "$ORIGIN/lib")
```

--------------------------------

### Install ICU Data File

Source: https://github.com/tomgilder/routemaster/blob/main/example/mobile_app/windows/CMakeLists.txt

Installs the ICU data file, which is required for internationalization and localization, to the application's data directory.

```cmake
install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)
```

--------------------------------

### Create a Page with Navigation

Source: https://github.com/tomgilder/routemaster/wiki/Getting-started

Example of a StatelessWidget that uses Routemaster to navigate to another page.

```dart
class PageOne extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Page one')),
      body: ElevatedButton(
        onPressed: () => Routemaster.of(context).push('two'),
        child: Text('Push page two'),
      ),
    );
  }
}
```

--------------------------------

### Project and Build Configuration

Source: https://github.com/tomgilder/routemaster/blob/main/example/deep_linking/linux/CMakeLists.txt

Sets the minimum CMake version, project name, executable name, and application ID. It also enables modern CMake behaviors and configures the installation path for bundled libraries.

```cmake
cmake_minimum_required(VERSION 3.10)
project(runner LANGUAGES CXX)

# The name of the executable created for the application. Change this to change
# the on-disk name of your application.
set(BINARY_NAME "deep_linking")
# The unique GTK application identifier for this application. See:
# https://wiki.gnome.org/HowDoI/ChooseApplicationID
set(APPLICATION_ID "com.example.deep_linking")

# Explicitly opt in to modern CMake behaviors to avoid warnings with recent
# versions of CMake.
cmake_policy(SET CMP0063 NEW)

# Load bundled libraries from the lib/ directory relative to the binary.
set(CMAKE_INSTALL_RPATH "$ORIGIN/lib")
```

--------------------------------

### Setup RoutemasterDelegate and MaterialApp.router

Source: https://context7.com/tomgilder/routemaster/llms.txt

Drives navigation using RoutemasterDelegate, which is passed to MaterialApp.router. Enables auth-state-driven route swapping via routesBuilder and context-free navigation.

```dart
// Standard setup
final delegate = RoutemasterDelegate(
  routesBuilder: (context) {
    // Rebuilds when AppState changes — swap maps for auth state
    final isLoggedIn = Provider.of<AppState>(context).isLoggedIn;
    return isLoggedIn ? loggedInMap : loggedOutMap;
  },
  observers: [MyAnalyticsObserver()],
);

void main() {
  runApp(
    MaterialApp.router(
      routerDelegate: delegate,
      routeInformationParser: const RoutemasterParser(),
    ),
  );
}

// Context-free navigation using the top-level delegate reference
delegate.push('/settings');
delegate.replace('/login');
```

--------------------------------

### Tab Page Routing Example

Source: https://github.com/tomgilder/routemaster/blob/main/README.md

Illustrates how to define routes for a TabPage, where child paths are mapped to specific tabs. Paths not matching tab definitions are handled by the parent.

```dart
 '/tabs': (route) => TabPage(child: HomePage(), paths: ['one', 'two']),

// First tab default page
'/tabs/one': (route) => MaterialPage(child: TabOnePage()),

// Second tab default page
'/tabs/two': (route) => MaterialPage(child: TabTwoPage()),

// Second tab sub-page: will be displayed in the 2nd tab because it
// starts with '/tabs/two'
'/tabs/two/subpage': (route) => MaterialPage(child: TabTwoPage()),

// Not a tab page: will not be displayed in in a tab
// because the path doesn't start with '/tabs/one' or '/tabs/two'
'/tabs/notInATab': (route) => MaterialPage(child: NotTabPage()),
```

--------------------------------

### Configure Flutter library and headers

Source: https://github.com/tomgilder/routemaster/blob/main/example/navigation_bar/linux/flutter/CMakeLists.txt

Defines the path to the Flutter Linux shared library and its header files. These are then exposed to the parent scope for use in installation steps.

```cmake
set(FLUTTER_LIBRARY "${EPHEMERAL_DIR}/libflutter_linux_gtk.so")

# Published to parent scope for install step.
set(FLUTTER_LIBRARY ${FLUTTER_LIBRARY} PARENT_SCOPE)
set(FLUTTER_ICU_DATA_FILE "${EPHEMERAL_DIR}/icudtl.dat" PARENT_SCOPE)
set(PROJECT_BUILD_DIR "${PROJECT_DIR}/build/" PARENT_SCOPE)
set(AOT_LIBRARY "${PROJECT_DIR}/build/lib/libapp.so" PARENT_SCOPE)
```

--------------------------------

### Set Minimum CMake Version and Project Name

Source: https://github.com/tomgilder/routemaster/blob/main/example/mobile_app/windows/CMakeLists.txt

Specifies the minimum required CMake version and declares the project name. This is a standard starting point for any CMake project.

```cmake
cmake_minimum_required(VERSION 3.14)
project(mobile_app LANGUAGES CXX)
```

--------------------------------

### Install AOT Library Conditionally in CMake

Source: https://github.com/tomgilder/routemaster/blob/main/example/book_store/linux/CMakeLists.txt

Installs the AOT library to the specified destination only when the build type is not 'Debug'. Ensures runtime components are correctly placed.

```cmake
if(NOT CMAKE_BUILD_TYPE MATCHES "Debug")
  install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()
```

--------------------------------

### Find and check system libraries with PkgConfig

Source: https://github.com/tomgilder/routemaster/blob/main/example/book_store/linux/flutter/CMakeLists.txt

This section uses PkgConfig to find and check for required system libraries like GTK, GLIB, and GIO. It ensures these dependencies are available and configured for the build.

```cmake
find_package(PkgConfig REQUIRED)
pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk+-3.0)
pkg_check_modules(GLIB REQUIRED IMPORTED_TARGET glib-2.0)
pkg_check_modules(GIO REQUIRED IMPORTED_TARGET gio-2.0)
```

--------------------------------

### Run Unit Tests (VM)

Source: https://github.com/tomgilder/routemaster/blob/main/CLAUDE.md

Execute unit tests using the Dart VM.

```bash
# Run unit tests (VM)
flutter test
```

--------------------------------

### Run Single Test File

Source: https://github.com/tomgilder/routemaster/blob/main/CLAUDE.md

Execute a specific unit test file.

```bash
# Run a single test file
flutter test test/router_test.dart
```

--------------------------------

### PageStackNavigator with Custom Page Builder

Source: https://context7.com/tomgilder/routemaster/llms.txt

Example of using PageStackNavigator with a custom page builder to filter pages, such as excluding modal overlays.

```dart
PageStackNavigator.builder(
  stack: myStack,
  builder: (pages) => pages.where((p) => p.name != 'overlay'),
)
```

--------------------------------

### Add Dependencies and Include Directories

Source: https://github.com/tomgilder/routemaster/blob/main/example/navigation_bar/windows/runner/CMakeLists.txt

Specifies the libraries and include directories required for the application. Application-specific dependencies should be added here.

```cmake
# Add dependency libraries and include directories. Add any application-specific
# dependencies here.
target_link_libraries(${BINARY_NAME} PRIVATE flutter flutter_wrapper_app)
target_include_directories(${BINARY_NAME} PRIVATE "${CMAKE_SOURCE_DIR}")
```

--------------------------------

### Configure Flutter library and headers

Source: https://github.com/tomgilder/routemaster/blob/main/example/book_store/linux/flutter/CMakeLists.txt

Sets up the Flutter library path and defines a list of Flutter library headers. The list_prepend function is used to add a directory prefix to each header file.

```cmake
set(FLUTTER_LIBRARY "${EPHEMERAL_DIR}/libflutter_linux_gtk.so")

list(APPEND FLUTTER_LIBRARY_HEADERS
  "fl_basic_message_channel.h"
  "fl_binary_codec.h"
  "fl_binary_messenger.h"
  "fl_dart_project.h"
  "fl_engine.h"
  "fl_json_message_codec.h"
  "fl_json_method_codec.h"
  "fl_message_codec.h"
  "fl_method_call.h"
  "fl_method_channel.h"
  "fl_method_codec.h"
  "fl_method_response.h"
  "fl_plugin_registrar.h"
  "fl_plugin_registry.h"
  "fl_standard_message_codec.h"
  "fl_standard_method_codec.h"
  "fl_string_codec.h"
  "fl_value.h"
  "fl_view.h"
  "flutter_linux.h"
)
list_prepend(FLUTTER_LIBRARY_HEADERS "${EPHEMERAL_DIR}/flutter_linux/")
```

--------------------------------

### Run Unit Tests (Web/Chrome)

Source: https://github.com/tomgilder/routemaster/blob/main/CLAUDE.md

Execute unit tests specifically targeting the Chrome browser.

```bash
# Run unit tests (web/Chrome)
flutter test --platform chrome
```

--------------------------------

### Nested Routing with CupertinoTabPage in Flutter

Source: https://github.com/tomgilder/routemaster/wiki/Routemaster-Flutter-scenarios

Set up nested navigation using `CupertinoTabPage`. This example defines a home page with tabs for 'feed', 'search', 'notifications', and 'settings'.

```dart
'/': (routeInfo) => CupertinoTabPage(
      child: HomePage(),
      paths: ['feed', 'search', 'notifications', 'settings'],
    ),
```

--------------------------------

### Apply Standard Build Settings

Source: https://github.com/tomgilder/routemaster/blob/main/example/navigation_bar/windows/runner/CMakeLists.txt

Applies a standard set of build settings to the executable target. This can be customized for applications requiring different build configurations.

```cmake
# Apply the standard set of build settings. This can be removed for applications
# that need different build settings.
apply_standard_settings(${BINARY_NAME})
```

--------------------------------

### Flutter and System Dependencies

Source: https://github.com/tomgilder/routemaster/blob/main/example/book_store/linux/CMakeLists.txt

Includes the Flutter build rules and finds necessary system libraries like GTK using PkgConfig. It also defines the application ID as a preprocessor macro.

```cmake
set(FLUTTER_MANAGED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/flutter")
add_subdirectory(${FLUTTER_MANAGED_DIR})

find_package(PkgConfig REQUIRED)
pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk+-3.0)

add_definitions(-DAPPLICATION_ID="${APPLICATION_ID}")
```

--------------------------------

### Define Private Routes with Underscore Segments

Source: https://context7.com/tomgilder/routemaster/llms.txt

Path segments starting with '_' are hidden from the browser address bar and blocked from direct navigation. Useful for multi-step wizards.

```dart
RouteMap(
  routes: {
    '/signup': (_) => MaterialPage(child: SignupPage()),

    // Private segment: address bar shows /signup, not /signup/_step-two
    '/signup/_step-two': (_) => MaterialPage(child: SignupStepTwoPage()),
    '/signup/_step-three': (_) => MaterialPage(child: SignupStepThreePage()),
  },
)

// Navigate to a private route normally from code:
Routemaster.of(context).push('/signup/_step-two');

// Typing /signup/_step-two in the browser bar → blocked by Routemaster
```

--------------------------------

### Runtime Output Directory Configuration

Source: https://github.com/tomgilder/routemaster/blob/main/example/book_store/linux/CMakeLists.txt

Configures the runtime output directory for the executable to a subdirectory. This is to ensure correct resource loading for bundled applications.

```cmake
set_target_properties(${BINARY_NAME}
  PROPERTIES
    RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/intermediates_do_not_run"
)
```

--------------------------------

### Deep Linking with Query Parameters in Flutter

Source: https://github.com/tomgilder/routemaster/wiki/Routemaster-Flutter-scenarios

Access query string values from `routeInfo.queryParameters`. This example shows how to retrieve a 'query' parameter from a URL like '/search?query=hello+world'.

```dart
'/search': (routeInfo) => MaterialPage(
    child: SearchPage(query: routeInfo.queryParameters['query']), // query is 'hello world'
)
```

--------------------------------

### System Dependencies (GTK)

Source: https://github.com/tomgilder/routemaster/blob/main/example/navigation_bar/linux/CMakeLists.txt

Finds and checks for the GTK+ 3.0 library using PkgConfig, making its imported target available for linking.

```cmake
find_package(PkgConfig REQUIRED)
pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk+-3.0)
```

--------------------------------

### Get Current Path Info

Source: https://github.com/tomgilder/routemaster/wiki/API-Quick-Start

Access current route information, including the full path, path parameters, and query parameters, within a widget using RouteData.of(context).

```dart
RouteData.of(context).path; // Full path: '/product/123?query=param'
RouteData.of(context).pathParameters; // Map: {'id': '123'}
RouteData.of(context).queryParameters; // Map: {'query': 'param'}
```

--------------------------------

### Configure Flutter Library and Dependencies

Source: https://github.com/tomgilder/routemaster/blob/main/example/mobile_app/linux/flutter/CMakeLists.txt

This section finds necessary system libraries using PkgConfig and sets up the Flutter library path and headers. It defines an INTERFACE library for Flutter, linking against system dependencies.

```cmake
find_package(PkgConfig REQUIRED)
pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk+-3.0)
pkg_check_modules(GLIB REQUIRED IMPORTED_TARGET glib-2.0)
pkg_check_modules(GIO REQUIRED IMPORTED_TARGET gio-2.0)

set(FLUTTER_LIBRARY "${EPHEMERAL_DIR}/libflutter_linux_gtk.so")

# Published to parent scope for install step.
set(FLUTTER_LIBRARY ${FLUTTER_LIBRARY} PARENT_SCOPE)
set(FLUTTER_ICU_DATA_FILE "${EPHEMERAL_DIR}/icudtl.dat" PARENT_SCOPE)
set(PROJECT_BUILD_DIR "${PROJECT_DIR}/build/" PARENT_SCOPE)
set(AOT_LIBRARY "${PROJECT_DIR}/build/lib/libapp.so" PARENT_SCOPE)

list(APPEND FLUTTER_LIBRARY_HEADERS
  "fl_basic_message_channel.h"
  "fl_binary_codec.h"
  "fl_binary_messenger.h"
  "fl_dart_project.h"
  "fl_engine.h"
  "fl_json_message_codec.h"
  "fl_json_method_codec.h"
  "fl_message_codec.h"
  "fl_method_call.h"
  "fl_method_channel.h"
  "fl_method_codec.h"
  "fl_method_response.h"
  "fl_plugin_registrar.h"
  "fl_plugin_registry.h"
  "fl_standard_message_codec.h"
  "fl_standard_method_codec.h"
  "fl_string_codec.h"
  "fl_value.h"
  "fl_view.h"
  "flutter_linux.h"
)
list_prepend(FLUTTER_LIBRARY_HEADERS "${EPHEMERAL_DIR}/flutter_linux/")
add_library(flutter INTERFACE)
target_include_directories(flutter INTERFACE
  "${EPHEMERAL_DIR}"
)
target_link_libraries(flutter INTERFACE "${FLUTTER_LIBRARY}")
target_link_libraries(flutter INTERFACE
  PkgConfig::GTK
  PkgConfig::GLIB
  PkgConfig::GIO
)
add_dependencies(flutter flutter_assemble)
```

--------------------------------

### Configure Tabbed Navigation with Routemaster

Source: https://github.com/tomgilder/routemaster/blob/main/example/EXAMPLE.md

Defines the routes for a tabbed interface, including a root route that manages two child tabs: '/feed' and '/settings'. This setup is essential for multi-tab applications.

```dart
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import 'package:routemaster/routemaster.dart';

void main() => runApp(MyApp());

final routes = RouteMap(
  routes: {
    '/': (_) => CupertinoTabPage(
          child: HomePage(),
          paths: ['/feed', '/settings'],
        ),
    '/feed': (_) => MaterialPage(child: FeedPage()),
    '/feed/profile/:id': (_) => MaterialPage(child: ProfilePage()),
    '/settings': (_) => MaterialPage(child: SettingsPage()),
  },
);

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp.router(
      routerDelegate: RoutemasterDelegate(routesBuilder: (_) => routes),
      routeInformationParser: RoutemasterParser(),
    );
  }
}

class HomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final tabState = CupertinoTabPage.of(context);

    return CupertinoTabScaffold(
      controller: tabState.controller,
      tabBuilder: tabState.tabBuilder,
      tabBar: CupertinoTabBar(
        items: [
          BottomNavigationBarItem(
            label: 'Feed',
            icon: Icon(CupertinoIcons.list_bullet),
          ),
          BottomNavigationBarItem(
            label: 'Settings',
            icon: Icon(CupertinoIcons.search),
          ),
        ],
      ),
    );
  }
}

class FeedPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: ElevatedButton(
          onPressed: () => Routemaster.of(context).push('profile/1'),
          child: Text('Feed page'),
        ),
      ),
    );
  }
}

class ProfilePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(),
      body: Center(child: Text('Profile page')),
    );
  }
}

class SettingsPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(body: Center(child: Text('Settings page')));
  }
}

```

--------------------------------

### Project and Build Configuration

Source: https://github.com/tomgilder/routemaster/blob/main/example/book_store/linux/CMakeLists.txt

Sets the minimum CMake version, project name, executable name, and application ID. It also configures build type and modern CMake policies.

```cmake
cmake_minimum_required(VERSION 3.10)
project(runner LANGUAGES CXX)

set(BINARY_NAME "book_store")
set(APPLICATION_ID "com.example.book_store")

cmake_policy(SET CMP0063 NEW)
set(CMAKE_INSTALL_RPATH "$ORIGIN/lib")

if(FLUTTER_TARGET_PLATFORM_SYSROOT)
  set(CMAKE_SYSROOT ${FLUTTER_TARGET_PLATFORM_SYSROOT})
  set(CMAKE_FIND_ROOT_PATH ${CMAKE_SYSROOT})
  set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
  set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
  set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
  set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
endif()

if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
  set(CMAKE_BUILD_TYPE "Debug" CACHE
    STRING "Flutter build mode" FORCE)
  set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS
    "Debug" "Profile" "Release")
endif()
```

--------------------------------

### Route Validation with Guards in Flutter

Source: https://github.com/tomgilder/routemaster/wiki/Routemaster-Flutter-scenarios

Implement route validation using the `Guard` widget. This example restricts access to '/feed/profile/:id' if the 'id' is not '1' or '2', redirecting to '/feed' on failure.

```dart
'/feed/profile/:id': (routeInfo) {
  return Guard(
    validate: (routeInfo) {
      return routeInfo.pathParameters['id'] == '1' ||
          routeInfo.pathParameters['id'] == '2';
    },
    onValidationFailed: (routeInfo, context) => Redirect('/feed'),
    child: MaterialPage(
      child: ProfilePage(
        id: routeInfo.pathParameters['id'],
        message: routeInfo.queryParameters['message'],
      ),
    ),
  );
},
```

--------------------------------

### Run Integration Tests

Source: https://github.com/tomgilder/routemaster/blob/main/CLAUDE.md

Execute integration tests using a specific script.

```bash
# Run integration tests
integration_test_app/run.sh
```

--------------------------------

### Navigate with Routemaster.of(context)

Source: https://context7.com/tomgilder/routemaster/llms.txt

Use Routemaster.of(context) inside widgets for navigation. Supports absolute paths (starting with '/') and relative paths. Query parameters can be passed for richer navigation.

```dart
class ProductListPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Products')),
      body: ListView(
        children: [
          // Absolute navigation
          ListTile(
            title: const Text('Widget A'),
            onTap: () => Routemaster.of(context).push('/products/123'),
          ),
          // Relative navigation (if current path is /products → /products/456)
          ListTile(
            title: const Text('Widget B'),
            onTap: () => Routemaster.of(context).push('456'),
          ),
          // Navigate with query parameters
          ListTile(
            title: const Text('Search'),
            onTap: () => Routemaster.of(context).push(
              '/search',
              queryParameters: {'q': 'flutter', 'page': '1'},
            ),
          ),
          // Replace current route (no back button entry)
          ListTile(
            title: const Text('Replace'),
            onTap: () => Routemaster.of(context).replace('/home'),
          ),
        ],
      ),
    );
  }
}
```

--------------------------------

### Analyze Code

Source: https://github.com/tomgilder/routemaster/blob/main/CLAUDE.md

Perform static analysis on the project code.

```bash
# Analyze code
flutter analyze
```

--------------------------------

### RouteData Path Property Change

Source: https://github.com/tomgilder/routemaster/wiki/Breaking-changes

The `path` property on `RouteData` now returns the path without the query string, similar to Dart's `Uri` object. Use `fullPath` to get the complete path including the query string.

```dart
routeData.path == '/route?query=string'
```

```dart
routeData.path == '/route'
routeData.fullPath == '/route?query=string'
```

--------------------------------

### Swap Routing Map at Runtime

Source: https://github.com/tomgilder/routemaster/blob/main/README.md

Demonstrates how to swap the entire routing map dynamically based on application state, such as user login status. This is useful for presenting different routes for logged-in and logged-out users.

```dart
final loggedOutMap = RouteMap(
  onUnknownRoute: (route, context) => Redirect('/'),
  routes: {
    '/': (_) => MaterialPage(child: LoginPage()),
  },
);

final loggedInMap = RouteMap(
  routes: {
    // Regular app routes
  },
);

MaterialApp.router(
  routerDelegate: RoutemasterDelegate(
    routesBuilder: (context) {
			// This will rebuild when AppState changes
      final appState = Provider.of<AppState>(context);
      return appState.isLoggedIn ? loggedInMap : loggedOutMap;
    },
  ),
  routeInformationParser: RoutemasterParser(),
);
```

--------------------------------

### Include Flutter Library and Tool Build Rules

Source: https://github.com/tomgilder/routemaster/blob/main/example/mobile_app/windows/CMakeLists.txt

Includes the build rules for the Flutter library and tools from the specified Flutter managed directory. This integrates Flutter's build system into the project.

```cmake
add_subdirectory(${FLUTTER_MANAGED_DIR})
```

--------------------------------

### Application Executable Definition

Source: https://github.com/tomgilder/routemaster/blob/main/example/deep_linking/linux/CMakeLists.txt

Defines the main executable for the application, listing its source files including generated plugin registration.

```cmake
# Define the application target. To change its name, change BINARY_NAME above,
# not the value here, or `flutter run` will no longer work.
#
# Any new source files that you add to the application should be added here.
add_executable(${BINARY_NAME}
  "main.cc"
  "my_application.cc"
  "${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc"
)

# Apply the standard set of build settings. This can be removed for applications
# that need different build settings.
apply_standard_settings(${BINARY_NAME})

# Add dependency libraries. Add any application-specific dependencies here.
target_link_libraries(${BINARY_NAME} PRIVATE flutter)
target_link_libraries(${BINARY_NAME} PRIVATE PkgConfig::GTK)

# Run the Flutter tool portions of the build. This must not be removed.
add_dependencies(${BINARY_NAME} flutter_assemble)
```

--------------------------------

### Include Application Runner Subdirectory

Source: https://github.com/tomgilder/routemaster/blob/main/example/mobile_app/windows/CMakeLists.txt

Includes the build rules for the application's runner, which typically contains the main entry point and platform-specific code.

```cmake
add_subdirectory("runner")
```

--------------------------------

### Enable Unicode Support

Source: https://github.com/tomgilder/routemaster/blob/main/example/mobile_app/windows/CMakeLists.txt

Adds preprocessor definitions to enable Unicode support in the project. This is important for handling international characters correctly.

```cmake
add_definitions(-DUNICODE -D_UNICODE)
```

--------------------------------

### Apply Standard Settings to Executable

Source: https://github.com/tomgilder/routemaster/blob/main/example/simple_example/linux/CMakeLists.txt

Applies the previously defined standard compilation settings to the application's executable target.

```cmake
apply_standard_settings(${BINARY_NAME})
```

--------------------------------

### Set Project Name and Minimum CMake Version

Source: https://github.com/tomgilder/routemaster/blob/main/example/navigation_bar/windows/CMakeLists.txt

Sets the minimum required CMake version and the project name for the navigation bar executable.

```cmake
cmake_minimum_required(VERSION 3.14)
project(navigation_bar LANGUAGES CXX)
set(BINARY_NAME "navigation_bar")
```

--------------------------------

### Create Flutter interface library and link dependencies

Source: https://github.com/tomgilder/routemaster/blob/main/example/book_store/linux/flutter/CMakeLists.txt

Defines an INTERFACE library target named 'flutter' and configures its include directories and link libraries. This includes system libraries found via PkgConfig and the Flutter library itself.

```cmake
add_library(flutter INTERFACE)
target_include_directories(flutter INTERFACE
  "${EPHEMERAL_DIR}"
)
target_link_libraries(flutter INTERFACE "${FLUTTER_LIBRARY}")
target_link_libraries(flutter INTERFACE
  PkgConfig::GTK
  PkgConfig::GLIB
  PkgConfig::GIO
)
```

--------------------------------

### Run Flutter Tool Build Steps

Source: https://github.com/tomgilder/routemaster/blob/main/example/navigation_bar/windows/runner/CMakeLists.txt

Ensures that the Flutter tool's build steps, specifically `flutter_assemble`, are executed as part of the target's dependencies. This step is essential and must not be removed.

```cmake
# Run the Flutter tool portions of the build. This must not be removed.
add_dependencies(${BINARY_NAME} flutter_assemble)
```

--------------------------------

### Flutter and System Dependencies

Source: https://github.com/tomgilder/routemaster/blob/main/example/deep_linking/linux/CMakeLists.txt

Includes the Flutter subdirectory for its build rules and checks for GTK+ 3.0 using PkgConfig. It also defines the APPLICATION_ID as a preprocessor macro.

```cmake
# Flutter library and tool build rules.
set(FLUTTER_MANAGED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/flutter")
add_subdirectory(${FLUTTER_MANAGED_DIR})

# System-level dependencies.
find_package(PkgConfig REQUIRED)
pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk+-3.0)

add_definitions(-DAPPLICATION_ID="${APPLICATION_ID}")
```

--------------------------------

### Sign-up FlowPage Route Map

Source: https://github.com/tomgilder/routemaster/wiki/PREVIEW:-Advanced-routing

Defines routes for a multi-step sign-up process using FlowPage. Ensure FlowPage is correctly implemented to manage the wizard steps.

```dart
 '/sign-up': (_) => FlowPage(
      child: SignUpPage(),
      paths: ['one', 'two', 'three'],
    ),

'/sign-up/one': (_) => MaterialPage(child: SignUpPageOne()),
'/sign-up/two': (_) => MaterialPage(child: SignUpPageTwo()),
'/sign-up/three': (_) => MaterialPage(child: SignUpPageThree()),

```

--------------------------------

### Define Application Executable

Source: https://github.com/tomgilder/routemaster/blob/main/example/navigation_bar/linux/CMakeLists.txt

Defines the main executable target for the application, listing its source files. New source files should be added here.

```cmake
add_executable(${BINARY_NAME}
  "main.cc"
  "my_application.cc"
  "${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc"
)
```

--------------------------------

### Implement Custom Navigation Observer

Source: https://github.com/tomgilder/routemaster/blob/main/README.md

Shows how to create a custom navigation observer by extending RoutemasterObserver to intercept and react to navigation events like route popping or route changes. Requires RoutemasterDelegate to be configured with the observer.

```dart
class MyObserver extends RoutemasterObserver {
	// RoutemasterObserver extends NavigatorObserver and
	// receives all nested Navigator events
  @override
  void didPop(Route route, Route? previousRoute) {
    print('Popped a route');
  }

	// Routemaster-specific observer method
  @override
  void didChangeRoute(RouteData routeData, Page page) {
    print('New route: ${routeData.path}');
  }
}

MaterialApp.router(
  routerDelegate: RoutemasterDelegate(
    observers: [MyObserver()],
    routesBuilder: (_) => routeMap,
  ),
  routeInformationParser: RoutemasterParser(),
);
```

--------------------------------

### Application Executable Definition

Source: https://github.com/tomgilder/routemaster/blob/main/example/book_store/linux/CMakeLists.txt

Defines the main executable target for the application, listing its source files. Standard build settings are then applied to this target.

```cmake
add_executable(${BINARY_NAME}
  "main.cc"
  "my_application.cc"
  "${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc"
)

apply_standard_settings(${BINARY_NAME})
```

--------------------------------

### Configure Runner Executable

Source: https://github.com/tomgilder/routemaster/blob/main/example/book_store/windows/runner/CMakeLists.txt

Defines the runner executable, lists its source files, and applies standard build settings. Includes specific definitions and library links for Windows compatibility.

```cmake
cmake_minimum_required(VERSION 3.14)
project(runner LANGUAGES CXX)

add_executable(${BINARY_NAME} WIN32
  "flutter_window.cpp"
  "main.cpp"
  "utils.cpp"
  "win32_window.cpp"
  "${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc"
  "Runner.rc"
  "runner.exe.manifest"
)
apply_standard_settings(${BINARY_NAME})
target_compile_definitions(${BINARY_NAME} PRIVATE "NOMINMAX")
target_link_libraries(${BINARY_NAME} PRIVATE flutter flutter_wrapper_app)
target_include_directories(${BINARY_NAME} PRIVATE "${CMAKE_SOURCE_DIR}")
add_dependencies(${BINARY_NAME} flutter_assemble)
```

--------------------------------

### Configure Routes with NotFound and Redirect

Source: https://context7.com/tomgilder/routemaster/llms.txt

Define route mappings, including handling unknown routes with NotFound and redirecting to other paths. Supports parameter forwarding for redirects.

```dart
RouteMap(
  onUnknownRoute: (path) => MaterialPage(child: NotFoundPage(path: path)),
  routes: {
    // Hard 404
    '/old-page': (_) => const NotFound(),

    // Simple redirect
    '/about-us': (_) => const Redirect('/about'),

    // Param-forwarding redirect: /user/42 → /profile/42
    '/user/:id': (_) => const Redirect('/profile/:id'),

    // Auth-gated redirect
    '/dashboard': (route) =>
        currentUser != null
          ? MaterialPage(child: DashboardPage())
          : const Redirect('/login'),

    // Logged-out map: catch-all redirect to login
    // (set as onUnknownRoute)
  },
)

// Logged-out catch-all
final loggedOutMap = RouteMap(
  onUnknownRoute: (_) => const Redirect('/'),
  routes: {
    '/': (_) => MaterialPage(child: LoginPage()),
  },
);
```

--------------------------------

### Linking Dependencies

Source: https://github.com/tomgilder/routemaster/blob/main/example/mobile_app/linux/CMakeLists.txt

Links the application executable against the Flutter library and GTK. This makes the necessary libraries available at link time.

```cmake
target_link_libraries(${BINARY_NAME} PRIVATE flutter)
target_link_libraries(${BINARY_NAME} PRIVATE PkgConfig::GTK)
```

--------------------------------

### 404 Unknown Route Handling

Source: https://github.com/tomgilder/routemaster/wiki/API-Quick-Start

Configure a default page to be displayed when an unknown URL is accessed using the onUnknownRoute callback in RouteMap.

```dart
RouteMap(
    onUnknownRoute: (route, context) {
        return MaterialPage(child: NotFoundPage());
    },
    routes: {
        '/': (_) => MaterialPage(child: HomePage()),
    },
)
```

--------------------------------

### Apply Standard Compilation Settings

Source: https://github.com/tomgilder/routemaster/blob/main/example/navigation_bar/windows/CMakeLists.txt

Defines a function to apply common compilation settings like C++ standard, warning levels, and exception handling to a target.

```cmake
function(APPLY_STANDARD_SETTINGS TARGET)
  target_compile_features(${TARGET} PUBLIC cxx_std_17)
  target_compile_options(${TARGET} PRIVATE /W4 /WX /wd"4100")
  target_compile_options(${TARGET} PRIVATE /EHsc)
  target_compile_definitions(${TARGET} PRIVATE "_HAS_EXCEPTIONS=0")
  target_compile_definitions(${TARGET} PRIVATE ")
endfunction()
```

--------------------------------

### Custom command to build Flutter library and headers

Source: https://github.com/tomgilder/routemaster/blob/main/example/book_store/linux/flutter/CMakeLists.txt

Defines a custom command that executes the Flutter tool backend script. This command is responsible for generating the Flutter library and its header files. The '_phony_' output is used to ensure the command runs on every build.

```cmake
add_custom_command(
  OUTPUT ${FLUTTER_LIBRARY} ${FLUTTER_LIBRARY_HEADERS}
    ${CMAKE_CURRENT_BINARY_DIR}/_phony_
  COMMAND ${CMAKE_COMMAND} -E env
    ${FLUTTER_TOOL_ENVIRONMENT}
    "${FLUTTER_ROOT}/packages/flutter_tools/bin/tool_backend.sh"
      ${FLUTTER_TARGET_PLATFORM} ${CMAKE_BUILD_TYPE}
  VERBATIM
)
```

--------------------------------

### Define Application Routes with RouteMap

Source: https://context7.com/tomgilder/routemaster/llms.txt

Maps URL path patterns to page builders. Supports dynamic segments, unknown route handling, and combining multiple route maps.

```dart
// Basic two-page app with a 404 handler
final routes = RouteMap(
  onUnknownRoute: (path) => MaterialPage(child: NotFoundPage(path: path)),
  routes: {
    '/': (_) => MaterialPage(child: HomePage()),
    '/products': (_) => MaterialPage(child: ProductListPage()),
    '/products/:id': (route) => MaterialPage(
      child: ProductDetailPage(id: route.pathParameters['id']!),
    ),
    '/search': (route) => MaterialPage(
      child: SearchPage(query: route.queryParameters['q']),
    ),
  },
);

// Splitting routes across teams/modules
final adminRoutes = RouteMap(routes: {
  '/admin': (_) => MaterialPage(child: AdminDashboard()),
  '/admin/users': (_) => MaterialPage(child: AdminUsersPage()),
});

final masterRouteMap = RouteMap(routes: {
  ...routes.routes,       // spread not directly supported; build per-map
  '/admin': (_) => MaterialPage(child: AdminDashboard()),
});
```

--------------------------------

### StackPage for Encapsulating Flows

Source: https://context7.com/tomgilder/routemaster/llms.txt

Use StackPage to host a navigation stack without tabs, ideal for wizards or multi-step flows. Navigating to the StackPage's path redirects to `defaultPath`. The inner stack is accessible via `StackPage.of(context).stack`.

```dart
// Route map
RouteMap(
  routes: {
    '/checkout': (_) => StackPage(
      child: CheckoutContainerPage(),
      defaultPath: 'step-1',  // relative — resolves to /checkout/step-1
    ),
    '/checkout/step-1': (_) => MaterialPage(child: CheckoutStep1()),
    '/checkout/step-2': (_) => MaterialPage(child: CheckoutStep2()),
    '/checkout/confirm': (_) => MaterialPage(child: CheckoutConfirmPage()),
  },
)

// Container page renders the inner stack
class CheckoutContainerPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final stackState = StackPage.of(context);

    return Scaffold(
      appBar: AppBar(title: const Text('Checkout')),
      body: PageStackNavigator(stack: stackState.stack),
    );
  }
}
```

--------------------------------

### Include Flutter Managed Directory and Runner

Source: https://github.com/tomgilder/routemaster/blob/main/example/navigation_bar/windows/CMakeLists.txt

Includes the Flutter managed directory and the application's runner subdirectory to integrate Flutter into the build.

```cmake
set(FLUTTER_MANAGED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/flutter")
add_subdirectory(${FLUTTER_MANAGED_DIR})
add_subdirectory("runner")
```

--------------------------------

### Project and Executable Naming

Source: https://github.com/tomgilder/routemaster/blob/main/example/navigation_bar/linux/CMakeLists.txt

Sets the executable name and GTK application identifier. Change BINARY_NAME to alter the on-disk name of your application.

```cmake
set(BINARY_NAME "navigation_bar")
set(APPLICATION_ID "com.example.navigation_bar")
```

--------------------------------

### Build Tab Page UI

Source: https://github.com/tomgilder/routemaster/blob/main/README.md

Build the UI for a tabbed page using `TabPage.of(context)` to access the tab controller and page stacks. Use `TabBarView` to display the content for each tab.

```dart
class HomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final tabPage = TabPage.of(context);

    return Scaffold(
      appBar: AppBar(
        bottom: TabBar(
          controller: tabPage.controller,
          tabs: [
            Tab(text: 'Feed'),
            Tab(text: 'Settings'),
          ],
        ),
      ),
      body: TabBarView(
        controller: tabPage.controller,
        children: [
          for (final stack in tabPage.stacks) PageStackNavigator(stack: stack),
        ],
      ),
    );
  }
}
```

--------------------------------

### Apply Standard Compilation Settings

Source: https://github.com/tomgilder/routemaster/blob/main/example/mobile_app/windows/CMakeLists.txt

A function to apply common compilation settings to a target. This includes setting the C++ standard, warning levels, and specific compile definitions.

```cmake
function(APPLY_STANDARD_SETTINGS TARGET)
  target_compile_features(${TARGET} PUBLIC cxx_std_17)
  target_compile_options(${TARGET} PRIVATE /W4 /WX /wd"4100")
  target_compile_options(${TARGET} PRIVATE /EHsc)
  target_compile_definitions(${TARGET} PRIVATE "_HAS_EXCEPTIONS=0")
  target_compile_definitions(${TARGET} PRIVATE "$<$<CONFIG:Debug>:_DEBUG>")
endfunction()
```