AGENTS.md

rtw - Adventure Motorcycle Trip Planner

A Rescript frontend application for planning adventure motorcycle trips with interactive maps and collaborative editing.

Required Skills (MUST INVOKE)

CRITICAL: Before writing or debugging Rescript code, you MUST invoke: - superpowers:working-in-rescript

This skill provides essential documentation and compiler guidance for Rescript development.

Technology Stack

Project Structure

src/
├── App.res              # Main app component
├── Main.res             # Entry point
├── Sheet.res            # Bottom sheet bindings
├── Maplibre.res         # Maplibre FFI bindings
└── ffi/
    ├── Preact.res       # Preact hooks/JSX
    ├── PreactDOM.res    # DOM bindings
    └── Doc.res          # Document API
test/                    # Test files (rescript-vitest)

Build Commands

pnpm exec rescript build    # Compile Rescript
pnpm run dev                # Dev server
pnpm run build              # Production build
pnpm vitest                 # Run tests

Coding Guidelines

Language Choice

• Write UI components in Rescript - use FFI bindings for JS interop
• Create typed interfaces in src/ffi/ for any new JavaScript libraries
• Prefer clean, simple code over adding dependencies

Rescript Patterns

• Use @jsx.component for React/Preact components
• Use @module and @val for external JS bindings
• Hooks are available via src/ffi/Preact.res (useState, useEffect, etc.)
• JSX transform uses Preact (configured in rescript.json)

FFI Example (from Maplibre.res)

@module("@vis.gl/react-maplibre") @jsx.component
external make: (~id: string=?, ~mapStyle: string=?) => Jsx.element = "Map"

Testing Requirements

Unit Tests (Required)

• All business logic must have unit tests
• Tests go in test/ directory
• Use rescript-vitest for Rescript-native testing
• Tests verify correctness of business logic implementations

Visual Verification (Optional)

• Only use playwright-cli when user explicitly asks to troubleshoot CSS/layout issues
• Not required for standard feature development

Future Integrations

TipTap Editor

• Rich text editor for trip notes and descriptions
• Will require FFI bindings in src/ffi/TipTap.res

Yjs CRDT

• Real-time collaborative editing
• Will integrate with TipTap for shared document editing
• Requires WebRTC or WebSocket provider bindings

Important Notes

• Always compile: Run pnpm exec rescript build after changes
• The compiler is strict - code must compile before committing
• Tailwind CSS v4 is used for styling (see vite.config.ts)
• Maptiler API key is loaded from VITE_MAPTILER_KEY env var