hotwire-native-path-config - SKILL.md Agent Skill

name: hotwire-native-path-config description: Configure and debug Hotwire Native path configurations for iOS and Android apps. Use when reviewing path-configuration.json files, adding routing rules for new screens, debugging modal/navigation issues, optimizing pull-to-refresh behavior, or when user mentions path configuration, path rules, or navigation routing in Hotwire Native context. allowed-tools: Read, Write, Edit, Glob, Grep

Hotwire Native Path Configuration

Configure URL routing rules that control navigation behavior in Hotwire Native iOS/Android apps.

Configuration Files in This Project

The paths below are examples from one app layout. Replace them with the current repo's actual remote and bundled path configuration files before editing.

File	Purpose
`public/configurations/ios_v1.json`	Remote iOS config (fetched from server)
`public/configurations/android_v1.json`	Remote Android config (fetched from server)
`ios/LifeMuse-iOS/path-configuration.json`	Bundled iOS config (offline fallback)
`android/app/src/main/assets/json/configuration.json`	Bundled Android config (offline fallback)

Keep bundled and remote configs in sync. Remote configs allow updates without app releases.

Quick Reference

Minimal Config Structure

{
  "settings": {},
  "rules": [
    { "patterns": [".*"], "properties": { "context": "default" } }
  ]
}

Common Rule Patterns

// Modal for /new and /edit paths
{ "patterns": ["/new$", "/edit$"], "properties": { "context": "modal", "pull_to_refresh_enabled": false } }

// Replace navigation (no back button)
{ "patterns": ["/dashboard$"], "properties": { "presentation": "replace" } }

// Hide navigation bar
{ "patterns": ["/auth"], "properties": { "navigation_bar_hidden": true } }

Platform Differences

Android requires uri property mapping to a registered Fragment:

// iOS
{ "patterns": [".*"], "properties": { "context": "default" } }

// Android (same rule)
{ "patterns": [".*"], "properties": { "context": "default", "uri": "hotwire://fragment/web" } }

Common Android URIs:

hotwire://fragment/web — Standard web view
hotwire://fragment/web/modal/sheet — Modal sheet

Adding a New Screen Rule

Identify the URL path pattern (use regex, $ for end anchor)
Determine presentation: default (push) or modal
Set pull-to-refresh: disable for modals/forms
Add rule to all four config files
Android: include appropriate uri

Debugging Checklist

Screen not showing as modal?

Verify "context": "modal" in properties
Check pattern matches the URL (test regex)
Ensure rule appears after the default .* rule

Pull-to-refresh not working?

Check pull_to_refresh_enabled: true
Look for later rules overriding the setting

Navigation stuck or unexpected?

Rules are sequential — later rules override earlier ones
Check for overlapping patterns

Android crash on navigation?

Verify uri property exists and maps to registered Fragment
Check HotwireDestinationDeepLink annotation in Kotlin code

Reference

See references/path-configuration.md for complete property documentation, modal styles, and advanced patterns.