Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

Race Condition in Modal State Management: Debugging a Premature Calendar Initialization

What Happened

During a recent development session on the sailjada.com booking system, we discovered a critical race condition in the modal initialization flow. The jadaOpenBook() function was opening the booking calendar modal before availability data had finished loading from the backend, allowing users to interact with an incomplete UI state. This created a poor user experience and potential data inconsistencies.

The root cause: the modal was being displayed synchronously while asynchronous data fetches were still in flight. Users could click on calendar dates before the availability state had been populated, leading to undefined behavior.

Technical Details of the Fix

The fix involved introducing a loading state gate in the modal initialization sequence. Rather than opening the modal immediately, we now:

  • Initialize isLoading: true when jadaOpenBook() is called
  • Fetch availability data asynchronously
  • Set isLoading: false only after data is successfully loaded
  • Display the modal UI in a disabled state while loading
  • Enable calendar interaction only when isLoading === false

The affected file structure:

/Users/cb/Documents/repos/sites/sailjada.com/
├── index.html (primary booking page)
├── releases/rc1/index.html (release candidate)
└── [20+ additional template pages with jadaOpenBook implementations]

Each file required the same synchronization pattern to be applied consistently. The 4.5 agent correctly identified all 22 pages containing jadaOpenBook references and applied the fix across the entire codebase.

Deployment Pipeline and Staging Validation

Following the STAGING RULE protocol, the fixed files were deployed to:

s3://queenofsandiego.com/_staging/sailjada/

This staging bucket serves as the intermediate verification environment before production promotion to the live CloudFront distribution. The staging URL follows the pattern:

https://queenofsandiego.com/_staging/sailjada/index.html

However, during validation of the staged deployment, a critical issue was discovered: the 4.5 agent introduced Python format-string syntax artifacts directly into JavaScript contexts.

The Format-String Escape Problem

The codebase contains Python-templated HTML files (indicated by placeholders like {STRIPE_LINK}). The 4.5 agent's fix included JavaScript state initialization that inadvertently duplicated the Python template escaping syntax:

// BROKEN - Python escape syntax in JavaScript
{{ isLoading: false }}

This is not valid JavaScript. Double-braces {{ }} are used by Python's format string system to escape literal braces, but they don't belong in JavaScript object literals.

The correct syntax should be:

// CORRECT - Pure JavaScript
{ isLoading: false }

A secondary discovery: many legitimate double-braces exist throughout the codebase in CSS contexts (unrelated to the race condition fix), so we had to distinguish between:

  • CSS double-braces (pre-existing, legitimate): Custom property fallbacks like background: var(--color, {{ fallback }})
  • JavaScript double-braces (the 4.5 error): State initialization that contaminated with template escape syntax
  • Python template placeholders (pre-existing): Format strings like {STRIPE_LINK}, {BOOKING_URL}

Recovery and Verification

Given the scope of corruption (23 files affected), the safest remediation path was to restore all local HTML files from the production S3 state, which was known to be stable:

aws s3 cp s3://sailjada.com/index.html ./index.html
aws s3 cp s3://sailjada.com/releases/rc1/index.html ./releases/rc1/index.html
# ... repeated for all 23 affected files

The production versions were confirmed to be functional: - No broken jadaOpenBook syntax - No Python template escaping artifacts in JavaScript - Proper booking widget implementations intact - Stripe payment integration links correctly populated

The staging deployment was then deleted to prevent accidental promotion of broken code:

aws s3 rm s3://queenofsandiego.com/_staging/sailjada/ --recursive

Root Cause Analysis

The 4.5 agent attempted to apply a legitimate fix (the race condition gate) but failed to account for the hybrid nature of the codebase:

  • Files are served as pre-rendered HTML from S3/CloudFront
  • Files are generated from Python templates during build/deployment
  • The templating layer uses double-brace escaping for literal braces
  • The agent wrote JavaScript state initialization without understanding this context

The agent received instructions to "apply the same fix to all pages" but lacked visibility into the templating pipeline architecture. It treated the files as plain HTML rather than as template outputs.

What's Ready vs. What Needs Testing

Ready for Production:

  • Current production state (all 23 files restored to stable S3 versions)
  • Existing booking calendar functionality
  • Stripe integration and payment flows
  • All deployed CloudFront distributions

In Need of Proper Implementation:

  • The race condition fix itself — the concept is sound, but implementation must follow the templating pipeline
  • Any changes must be made at the template source level, not in the final HTML
  • The fix needs testing in a proper build environment where Python templating is applied
  • Staging validation must account for both pre-template and post-template states

Recommended Path Forward

To properly implement the modal race condition fix:

  1. Identify the Python template source files (likely in a templates/ directory with .py or .jinja extensions)
  2. Apply the isLoading state guard at the template level, using proper Python variable injection
  3. Ensure the template system properly escapes any literal braces needed in output
  4. Build and test locally before staging
  5. Deploy the entire template source to staging, not individual HTML files
  6. Verify the rendered output contains correct JavaScript syntax and no template artifacts
  7. Promote to production only after staging validation

The lesson: multi-layered systems (template rendering → HTML output → CloudFront CDN) require understanding the full pipeline before making changes at the output layer.