[ychae517]

Description

Adds a new turn by turn directions format to replace the raw turn angle (Turn.degrees). Each step now has an enum type that maps directly to an instruction the frontend shows, so the FE doesn't need to work out from angles alone which branches exist. This PR only adds the types. Mock data and wiring them into the walking response come in the follow-up PR.

Format

Directions is an ordered array of DirectionStep, a discriminated union on type:

type	extra fields	meaning
depart		start walking (always first)
turn	direction: slight_left | left | sharp_left | slight_right | right | sharp_right	turn at an intersection or a sharp enough bend
continue		go straight where another branch could be mistaken for the route
cross	street: string | null	cross a street (crosswalk data from #93 will feed this)
arrive		end of the walking path (always last)

Every step also has:

• path_index: index into path_coords where the step happens
• distance: meters until the next step (0 for arrive)
• onto: string | null: name of the street/path walked along after this step
• landmark: string | null: nearby landmark to anchor the instruction (carried over from the old Turn.landmark)

Notes:

• Defined as Zod schemas with .meta({ id }), so they slot into the OpenAPI generation in the docu/* branches. Uses z.nullable instead of optional fields.
• Field names are snake_case to match WalkingResponse (path_coords).
• The enums can grow as the algorithm (basic turn by turn algorithm #98) improves, so the FE should fall back to a generic instruction for any type/direction it doesn't recognize.

Example:

[
  { "type": "depart", "path_index": 0, "distance": 40, "onto": "State St", "landmark": null },
  { "type": "turn", "direction": "left", "path_index": 5, "distance": 20, "onto": null, "landmark": "Hatcher Library" },
  { "type": "cross", "street": "S University Ave", "path_index": 8, "distance": 15, "onto": null, "landmark": null },
  { "type": "arrive", "path_index": 12, "distance": 0, "onto": null, "landmark": null }
]

Type of Change

• New feature (feat)
• Bug fix (fix)
• Refactor / code improvement
• Dependency / build update
• Documentation
• Other (explain)

Changed Files

• src/walking/directions.ts (new)
  • Zod schemas and inferred types: TurnDirection, DirectionStep (plus a schema per step), DirectionStepType, Directions

Related Issues

Part of #97 (step 1: types). Prereq of the #97 mock data PR and #98.

Does your code rely on another PR

No. WalkingResponse.directions (the old format) is in #101, which hasn't merged. Swapping it to Directions happens in the mock data PR.

Testing Done

Vitest:

• existing test(s) with coverage: none. Types only, nothing imports this yet
• new tests added: none. Relying on CI tsc --noEmit and typedoc

Checklist

• Commit messages follow Conventional Commits
• PR title follows <type>(scope): short description
• PR target branch is not main and is our current working update branch (e.g. maizebus2.1, dev)
• No print() / debugPrint() / console.log() left in production code
• Secrets / keys not committed

🤖 Generated with Claude Code