[P1] Correct meal-plan date and timezone semantics

[postigodev]

Context

Meal-plan server and client code currently derive civil dates with a mixture of local Date mutation and toISOString().slice(0, 10). A calendar day such as 2026-07-16 is not an instant, but converting local midnight to UTC can shift the represented date. Server and browser timezone differences can also produce different current weeks near midnight or daylight-saving transitions.

Meal planning must have deterministic date-only semantics across SSR, hydration, APIs, and users in different timezones.

Scope

• Define the source of the user's planning timezone and its fallback behavior.
• Treat meal-plan YYYY-MM-DD values as civil/date-only values, separately from timestamps and instants.
• Establish one deterministic definition of week start and current day for server and client rendering.
• Remove UTC ISO conversion patterns that can change a civil date.
• Use Temporal/date-only helpers or an equivalent tested abstraction rather than ad hoc Date arithmetic.
• Keep storage/API serialization independent from locale-specific display formatting.
• Define behavior when a user changes timezone or travels.
• Audit meal events, range queries, month/week generation, cart generation from meal events, and account nutrition summaries for the same issue.
• Add compatibility/migration guidance if existing persisted values or API contracts need reinterpretation.
• Add tests around midnight, DST boundaries, leap days, month/year transitions, and extreme offsets.

Acceptance criteria

• The same meal-plan date key represents the same civil day on server and client.
• SSR and hydration choose the same current day and week for a given user timezone.
• Date-only values are not converted through UTC in a way that changes the day.
• Week navigation and month generation are deterministic across DST and month/year boundaries.
• API/storage semantics are documented separately from locale display formatting.
• Timezone changes have an explicit product rule and do not silently move existing planned meals.
• Tests cover UTC-12, UTC, UTC+14, relevant DST zones, midnight transitions, leap day, and hydration.
• Contract changes are covered by [P1] Add cross-layer contract compatibility tests #86 where applicable.

Related

• Cross-layer contract compatibility tests: [P1] Add cross-layer contract compatibility tests #86.
• Launch-critical browser validation: [P0] Add launch-critical validation and staging smoke tests to dev and release CI #77.
• App-wide loading/error behavior: [P1] Establish app-wide loading, error, offline, and stale-data states #113.

Out of scope

• Calendar-provider integrations.
• Automatic location tracking solely to infer timezone.