Add break time feature to schedule blocks

- Admin: per-block "Break Time" checkbox + duration (min) setting; new
  Break Activities section (global list, same pattern as Morning Routine)
- Dashboard: break timer section appears on blocks with break enabled;
  Start/Pause/Resume/Reset controls work independently of the main timer
- TV: left column switches to amber break badge + countdown during break;
  center column shows configurable Break Activities list
- Backend: break_time_enabled/break_time_minutes columns on schedule_blocks
  (auto-migrated on startup); break_activity_items table + CRUD router;
  break timer events (break_start/pause/resume/reset) stored as TimerEvents
  and broadcast via WebSocket; break_activities included in dashboard
  snapshot and session_update broadcast

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

backend/app/main.py

@@ -9,7 +9,7 @@ from app.config import get_settings
 from app.database import engine
 from app.models import Base
 from app.routers import auth, users, children, subjects, schedules, sessions, logs, dashboard
-from app.routers import morning_routine
+from app.routers import morning_routine, break_activity
 from app.websocket.manager import manager
 
 settings = get_settings()
@@ -33,6 +33,8 @@ async def lifespan(app: FastAPI):
         await _add_column_if_missing(conn, "schedule_templates", "day_start_time", "TIME NULL")
         await _add_column_if_missing(conn, "schedule_templates", "day_end_time", "TIME NULL")
         await _add_column_if_missing(conn, "schedule_blocks", "duration_minutes", "INT NULL")
+        await _add_column_if_missing(conn, "schedule_blocks", "break_time_enabled", "TINYINT(1) NOT NULL DEFAULT 0")
+        await _add_column_if_missing(conn, "schedule_blocks", "break_time_minutes", "INT NULL")
         await _add_column_if_missing(conn, "children", "strikes", "INT NOT NULL DEFAULT 0")
         await _add_column_if_missing(conn, "users", "timezone", "VARCHAR(64) NOT NULL DEFAULT 'UTC'")
     yield
@@ -64,6 +66,7 @@ app.include_router(schedules.router)
 app.include_router(sessions.router)
 app.include_router(logs.router)
 app.include_router(morning_routine.router)
+app.include_router(break_activity.router)
 app.include_router(dashboard.router)
 
 

backend/app/models/__init__.py

@@ -7,6 +7,7 @@ from app.models.schedule import ScheduleTemplate, ScheduleBlock
 from app.models.session import DailySession, TimerEvent, TimerEventType
 from app.models.activity import ActivityLog
 from app.models.morning_routine import MorningRoutineItem
+from app.models.break_activity import BreakActivityItem
 from app.models.strike import StrikeEvent
 
 __all__ = [
@@ -23,5 +24,6 @@ __all__ = [
     "TimerEventType",
     "ActivityLog",
     "MorningRoutineItem",
+    "BreakActivityItem",
     "StrikeEvent",
 ]

backend/app/models/break_activity.py

@@ -0,0 +1,15 @@
+from sqlalchemy import ForeignKey, Integer, Text
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.models.base import Base
+
+
+class BreakActivityItem(Base):
+    __tablename__ = "break_activity_items"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
+    text: Mapped[str] = mapped_column(Text, nullable=False)
+    order_index: Mapped[int] = mapped_column(Integer, default=0)
+
+    user: Mapped["User"] = relationship("User")  # noqa: F821

backend/app/models/schedule.py

@@ -43,6 +43,8 @@ class ScheduleBlock(Base):
     label: Mapped[str | None] = mapped_column(String(100), nullable=True)  # override subject name
     notes: Mapped[str | None] = mapped_column(Text, nullable=True)
     order_index: Mapped[int] = mapped_column(Integer, default=0)
+    break_time_enabled: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
+    break_time_minutes: Mapped[int | None] = mapped_column(Integer, nullable=True)
 
     template: Mapped["ScheduleTemplate"] = relationship("ScheduleTemplate", back_populates="blocks")
     subject: Mapped["Subject | None"] = relationship("Subject", back_populates="schedule_blocks")  # noqa: F821

backend/app/routers/break_activity.py

@@ -0,0 +1,97 @@
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+
+from app.dependencies import get_db, get_current_user
+from app.models.break_activity import BreakActivityItem
+from app.models.user import User
+
+router = APIRouter(prefix="/api/break-activities", tags=["break-activities"])
+
+
+class BreakActivityItemOut(BaseModel):
+    id: int
+    text: str
+    order_index: int
+    model_config = {"from_attributes": True}
+
+
+class BreakActivityItemCreate(BaseModel):
+    text: str
+    order_index: int = 0
+
+
+class BreakActivityItemUpdate(BaseModel):
+    text: str | None = None
+    order_index: int | None = None
+
+
+@router.get("", response_model=list[BreakActivityItemOut])
+async def list_items(
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    result = await db.execute(
+        select(BreakActivityItem)
+        .where(BreakActivityItem.user_id == current_user.id)
+        .order_by(BreakActivityItem.order_index, BreakActivityItem.id)
+    )
+    return result.scalars().all()
+
+
+@router.post("", response_model=BreakActivityItemOut, status_code=status.HTTP_201_CREATED)
+async def create_item(
+    body: BreakActivityItemCreate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    item = BreakActivityItem(user_id=current_user.id, text=body.text, order_index=body.order_index)
+    db.add(item)
+    await db.commit()
+    await db.refresh(item)
+    return item
+
+
+@router.patch("/{item_id}", response_model=BreakActivityItemOut)
+async def update_item(
+    item_id: int,
+    body: BreakActivityItemUpdate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    result = await db.execute(
+        select(BreakActivityItem).where(
+            BreakActivityItem.id == item_id,
+            BreakActivityItem.user_id == current_user.id,
+        )
+    )
+    item = result.scalar_one_or_none()
+    if not item:
+        raise HTTPException(status_code=404, detail="Item not found")
+    if body.text is not None:
+        item.text = body.text
+    if body.order_index is not None:
+        item.order_index = body.order_index
+    await db.commit()
+    await db.refresh(item)
+    return item
+
+
+@router.delete("/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_item(
+    item_id: int,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    result = await db.execute(
+        select(BreakActivityItem).where(
+            BreakActivityItem.id == item_id,
+            BreakActivityItem.user_id == current_user.id,
+        )
+    )
+    item = result.scalar_one_or_none()
+    if not item:
+        raise HTTPException(status_code=404, detail="Item not found")
+    await db.delete(item)
+    await db.commit()

backend/app/routers/dashboard.py

@@ -12,6 +12,7 @@ from sqlalchemy.orm import selectinload
 from app.dependencies import get_db
 from app.models.child import Child
 from app.models.morning_routine import MorningRoutineItem
+from app.models.break_activity import BreakActivityItem
 from app.models.schedule import ScheduleBlock, ScheduleTemplate
 from app.models.subject import Subject  # noqa: F401 — needed for selectinload chain
 from app.models.session import DailySession, TimerEvent
@@ -86,6 +87,13 @@ async def get_dashboard(child_id: int, db: AsyncSession = Depends(get_db)):
     )
     morning_routine = [item.text for item in routine_result.scalars().all()]
 
+    break_result = await db.execute(
+        select(BreakActivityItem)
+        .where(BreakActivityItem.user_id == child.user_id)
+        .order_by(BreakActivityItem.order_index, BreakActivityItem.id)
+    )
+    break_activities = [item.text for item in break_result.scalars().all()]
+
     return DashboardSnapshot(
         session=session,
         child=child,
@@ -96,4 +104,5 @@ async def get_dashboard(child_id: int, db: AsyncSession = Depends(get_db)):
         day_start_time=day_start_time,
         day_end_time=day_end_time,
         morning_routine=morning_routine,
+        break_activities=break_activities,
     )

backend/app/routers/sessions.py

@@ -8,12 +8,13 @@ from sqlalchemy.orm import selectinload
 from app.dependencies import get_db, get_current_user
 from app.models.child import Child
 from app.models.morning_routine import MorningRoutineItem
+from app.models.break_activity import BreakActivityItem
 from app.models.schedule import ScheduleBlock, ScheduleTemplate
 from app.models.subject import Subject  # noqa: F401 — needed for selectinload chain
 from app.models.session import DailySession, TimerEvent
 from app.models.user import User
 from app.schemas.session import DailySessionOut, SessionStart, TimerAction
-from app.utils.timer import compute_block_elapsed
+from app.utils.timer import compute_block_elapsed, compute_break_elapsed
 from app.websocket.manager import manager
 
 router = APIRouter(prefix="/api/sessions", tags=["sessions"])
@@ -49,6 +50,8 @@ async def _broadcast_session(db: AsyncSession, session: DailySession) -> None:
                 "duration_minutes": b.duration_minutes,
                 "label": b.label,
                 "order_index": b.order_index,
+                "break_time_enabled": b.break_time_enabled,
+                "break_time_minutes": b.break_time_minutes,
             }
             for b in blocks_result.scalars().all()
         ]
@@ -82,6 +85,15 @@ async def _broadcast_session(db: AsyncSession, session: DailySession) -> None:
         )
         morning_routine = [item.text for item in routine_result.scalars().all()]
 
+    break_activities: list[str] = []
+    if child:
+        break_result = await db.execute(
+            select(BreakActivityItem)
+            .where(BreakActivityItem.user_id == child.user_id)
+            .order_by(BreakActivityItem.order_index, BreakActivityItem.id)
+        )
+        break_activities = [item.text for item in break_result.scalars().all()]
+
     payload = {
         "event": "session_update",
         "session": {
@@ -96,6 +108,7 @@ async def _broadcast_session(db: AsyncSession, session: DailySession) -> None:
         "day_start_time": day_start_time,
         "day_end_time": day_end_time,
         "morning_routine": morning_routine,
+        "break_activities": break_activities,
     }
     await manager.broadcast(session.child_id, payload)
 
@@ -185,6 +198,35 @@ async def timer_action(
     if not session:
         raise HTTPException(status_code=404, detail="Session not found")
 
+    # Break-time events are handled separately — they don't switch blocks or
+    # trigger implicit pauses.  Just record the event and broadcast.
+    BREAK_EVENTS = {"break_start", "break_pause", "break_resume", "break_reset"}
+    if body.event_type in BREAK_EVENTS:
+        block_id = body.block_id or session.current_block_id
+        event = TimerEvent(
+            session_id=session.id,
+            block_id=block_id,
+            event_type=body.event_type,
+        )
+        db.add(event)
+        await db.commit()
+        await db.refresh(session)
+
+        break_elapsed_seconds = 0
+        if body.event_type in ("break_start", "break_reset") and block_id:
+            break_elapsed_seconds, _ = await compute_break_elapsed(db, session.id, block_id)
+
+        ws_payload = {
+            "event": body.event_type,
+            "session_id": session.id,
+            "block_id": block_id,
+            "current_block_id": session.current_block_id,
+            "is_active": session.is_active,
+            "break_elapsed_seconds": break_elapsed_seconds,
+        }
+        await manager.broadcast(session.child_id, ws_payload)
+        return session
+
     # When switching to a different block (start / select / reset), implicitly
     # pause the previous block so the activity log stays accurate.
     prev_block_id = None

backend/app/schemas/schedule.py

@@ -11,6 +11,8 @@ class ScheduleBlockCreate(BaseModel):
     label: str | None = None
     notes: str | None = None
     order_index: int = 0
+    break_time_enabled: bool = False
+    break_time_minutes: int | None = None
 
 
 class ScheduleBlockUpdate(BaseModel):
@@ -21,6 +23,8 @@ class ScheduleBlockUpdate(BaseModel):
     label: str | None = None
     notes: str | None = None
     order_index: int | None = None
+    break_time_enabled: bool | None = None
+    break_time_minutes: int | None = None
 
 
 class ScheduleBlockOut(BaseModel):
@@ -33,6 +37,8 @@ class ScheduleBlockOut(BaseModel):
     label: str | None
     notes: str | None
     order_index: int
+    break_time_enabled: bool
+    break_time_minutes: int | None
 
     model_config = {"from_attributes": True}
 

backend/app/schemas/session.py

@@ -47,3 +47,4 @@ class DashboardSnapshot(BaseModel):
     day_start_time: time | None = None
     day_end_time: time | None = None
     morning_routine: list[str] = []  # text items shown on TV during greeting state
+    break_activities: list[str] = []  # text items shown on TV during break time

backend/app/utils/timer.py

@@ -42,3 +42,36 @@ async def compute_block_elapsed(
 
     is_paused = bool(tick_events) and tick_events[-1].event_type == "pause"
     return int(elapsed), is_paused
+
+
+async def compute_break_elapsed(
+    db: AsyncSession, session_id: int, block_id: int
+) -> tuple[int, bool]:
+    """Return (break_elapsed_seconds, is_break_paused) for a block's break timer."""
+    tick_result = await db.execute(
+        select(TimerEvent)
+        .where(
+            TimerEvent.session_id == session_id,
+            TimerEvent.block_id == block_id,
+            TimerEvent.event_type.in_(["break_start", "break_resume", "break_pause", "break_reset"]),
+        )
+        .order_by(TimerEvent.occurred_at)
+    )
+    tick_events = tick_result.scalars().all()
+
+    elapsed = 0.0
+    last_start = None
+    for e in tick_events:
+        if e.event_type == "break_reset":
+            elapsed = 0.0
+            last_start = e.occurred_at
+        elif e.event_type in ("break_start", "break_resume"):
+            last_start = e.occurred_at
+        elif e.event_type == "break_pause" and last_start:
+            elapsed += (e.occurred_at - last_start).total_seconds()
+            last_start = None
+    if last_start:
+        elapsed += (datetime.utcnow() - last_start).total_seconds()
+
+    is_paused = bool(tick_events) and tick_events[-1].event_type == "break_pause"
+    return int(elapsed), is_paused