Backfill Algorithm Implementation

The timeline grid was not matching the volume grid due to overflow situations. This occurred when the cron job (running every 10 minutes) reported screen time increases greater than 10 minutes in a single interval.

• Record at 9:55 AM: 0 minutes
• Record at 10:00 AM: 100 minutes
• Problem: 100 minutes appeared in a 5-minute gap
• Old behavior: Clamp to 10 minutes, lose 90 minutes to "Artifacts"
• New behavior: Distribute 100 minutes backwards into empty blocks

1. Iterate through time blocks sequentially (7:00 AM - 11:40 PM, 100 blocks of 10 minutes each)

2. Calculate raw usage for each block based on cumulative screen time data

3. Handle overflow:

   • If usage ≤ 10 minutes: Use actual usage
   • If usage > 10 minutes:
     • Fill current block with 10 minutes
     • Add remainder to backlog

4. Backfill process:

   • When backlog exists, work backwards from current block
   • Fill previous empty blocks until backlog is exhausted
   • Each block can hold maximum 10 minutes

5. Volume grid synchronization:

   • Volume grid now uses timeline's active block count instead of simple totalMinutes/10
   • This ensures both grids always match in number of filled blocks

// Three-pass algorithm:
// 1. Calculate raw usage for each block
// 2. Apply backfill algorithm with backlog management
// 3. Generate HTML and calculate statistics

// Volume grid now syncs with timeline:
const actualActiveBlocks = timelineStats?.visibleBlocksCount || numFilled;

• Volume Preservation: All screen time minutes are represented in the grid
• Timeline Approximation: Usage is distributed backwards from sync points
• Visual Clarity: No single "exploded" blocks with impossible usage
• Grid Synchronization: Volume and timeline grids always show same number of active blocks
• Enhanced Tooltips: Show backfilled vs. direct usage
• Statistics Tracking: New "Backfilled" metric in blue

• ❌ Lost minutes to "Artifacts/Bursts"
• ❌ Timeline grid didn't match volume grid
• ❌ Poor visual representation of actual usage
• ❌ Volume showed 38 blocks, timeline showed 41 blocks

• ✅ Volume: Total red blocks match total screen time
• ✅ Timeline: Better approximation of when usage occurred
• ✅ Synchronization: Both grids show identical number of active blocks
• ✅ Statistics: Clear breakdown of backfilled vs. direct usage
• ✅ Tooltips: Enhanced information about block contents

The original volume grid used simple math: Math.ceil(totalMinutes / 10) to determine filled blocks. However, the backfill algorithm can create more active blocks than this simple calculation suggests.

Example:

• 380 minutes ÷ 10 = 38 blocks (volume grid)
• But with overflow backfill: 41 blocks become active (timeline grid)
• Reason: Overflow gets distributed backwards, activating additional blocks

The volume grid now uses the timeline's actual active block count:

const actualActiveBlocks = timelineStats?.visibleBlocksCount || numFilled;

This ensures perfect synchronization between both grids.

• clearspace-100-blocks.ts: Main implementation with backfill algorithm and grid synchronization
• backfill-demo.ts: Demonstration endpoint showing algorithm in action
• debug-mismatch.ts: Debug tool for investigating volume/timeline discrepancies

• Backfilled: Minutes distributed backwards (shown in blue)
• Artifacts/Bursts: Only unresolved overflow (should be minimal now)

Visit /clearspace_screen_time/backfill-demo.ts to see a step-by-step demonstration of the algorithm with sample overflow data.