@startsimpli/ui 0.4.168 → 0.4.170

package/src/components/timer/__tests__/useIdleReturn.test.tsx

@@ -0,0 +1,59 @@
+import { renderHook, act } from '@testing-library/react'
+import { useIdleReturn, type IdleSignal } from '../useIdleReturn'
+
+function bus() {
+  const subs = new Set<(e: IdleSignal) => void>()
+  return {
+    subscribe: (cb: (e: IdleSignal) => void) => {
+      subs.add(cb)
+      return () => subs.delete(cb)
+    },
+    emit: (e: IdleSignal) => subs.forEach((s) => s(e)),
+  }
+}
+
+const t = (s: string) => new Date(s).getTime()
+const idleSince = t('2026-10-31T10:00:00.000Z')
+const ts = t('2026-10-31T10:20:00.000Z')
+
+describe('useIdleReturn', () => {
+  it('opens a prompt on idle-end while a timer runs, with the idle duration', () => {
+    const b = bus()
+    const { result } = renderHook(() => useIdleReturn({ subscribe: b.subscribe, runningSince: t('2026-10-31T09:00:00.000Z') }))
+    expect(result.current.prompt).toBeNull()
+    act(() => b.emit({ type: 'idle-start', ts: idleSince, idleSince }))
+    expect(result.current.prompt).toBeNull()
+    act(() => b.emit({ type: 'idle-end', ts, idleSince }))
+    expect(result.current.prompt).toEqual({ idleSince, until: ts, seconds: 1200 })
+  })
+
+  it('ignores a return when no timer is running', () => {
+    const b = bus()
+    const { result } = renderHook(() => useIdleReturn({ subscribe: b.subscribe, runningSince: null }))
+    act(() => b.emit({ type: 'idle-end', ts, idleSince }))
+    expect(result.current.prompt).toBeNull()
+  })
+
+  it('ignores idle shorter than the minimum', () => {
+    const b = bus()
+    const { result } = renderHook(() => useIdleReturn({ subscribe: b.subscribe, runningSince: 0, minSeconds: 600 }))
+    act(() => b.emit({ type: 'idle-end', ts: idleSince + 120_000, idleSince }))
+    expect(result.current.prompt).toBeNull()
+  })
+
+  it('dismiss clears it, and non-idle events never open it', () => {
+    const b = bus()
+    const { result } = renderHook(() => useIdleReturn({ subscribe: b.subscribe, runningSince: 0 }))
+    act(() => b.emit({ type: 'lock', ts }))
+    expect(result.current.prompt).toBeNull()
+    act(() => b.emit({ type: 'idle-end', ts, idleSince }))
+    expect(result.current.prompt).not.toBeNull()
+    act(() => result.current.dismiss())
+    expect(result.current.prompt).toBeNull()
+  })
+
+  it('works without a subscription (browser build)', () => {
+    const { result } = renderHook(() => useIdleReturn({ subscribe: undefined, runningSince: 0 }))
+    expect(result.current.prompt).toBeNull()
+  })
+})

package/src/components/timer/__tests__/useRunningTimer.test.tsx

@@ -0,0 +1,167 @@
+import { renderHook, act, waitFor } from '@testing-library/react'
+import { useRunningTimer } from '../useRunningTimer'
+import type { IntervalStore, TimedEntry } from '../interval-logic'
+
+const conflict = () => Object.assign(new Error('conflict'), { status: 409 })
+const stale = () => Object.assign(new Error('stale'), { status: 412 })
+
+function fakeStore(initial: TimedEntry | null = null) {
+  let running = initial
+  let seq = 0
+  const calls: string[] = []
+  const store: IntervalStore & { calls: string[]; setRunning(e: TimedEntry | null): void; failNext: { create?: Error; update?: Error } } = {
+    calls,
+    failNext: {},
+    setRunning(e) {
+      running = e
+    },
+    async findRunning() {
+      calls.push('find')
+      return running
+    },
+    async create(input) {
+      calls.push(`create:${input.endedAt ?? 'open'}`)
+      if (store.failNext.create) {
+        const e = store.failNext.create
+        store.failNext.create = undefined
+        throw e
+      }
+      const e: TimedEntry = { id: `n${++seq}`, version: 1, startedAt: input.startedAt, endedAt: input.endedAt, projectId: input.projectId ?? null, note: input.note ?? '' }
+      if (!input.endedAt) running = e
+      return e
+    },
+    async update(entry, patch) {
+      calls.push(`update:${JSON.stringify(patch)}`)
+      if (store.failNext.update) {
+        const e = store.failNext.update
+        store.failNext.update = undefined
+        throw e
+      }
+      const next = { ...entry, ...patch, version: (entry.version ?? 0) + 1 } as TimedEntry
+      if (running?.id === entry.id) running = next.endedAt ? null : next
+      return next
+    },
+    async remove() {},
+  }
+  return store
+}
+
+const open = (over: Partial<TimedEntry> = {}): TimedEntry => ({
+  id: 'r1', version: 1, startedAt: '2026-10-31T09:00:00.000Z', endedAt: null, projectId: 'p1', note: 'n', ...over,
+})
+
+describe('useRunningTimer', () => {
+  it('loads an already running entry and counts elapsed from now()', async () => {
+    const store = fakeStore(open())
+    const now = jest.fn(() => new Date('2026-10-31T09:00:10.000Z').getTime())
+    const { result } = renderHook(() => useRunningTimer({ store, now, tickMs: 0 }))
+    await waitFor(() => expect(result.current.status).toBe('running'))
+    expect(result.current.elapsed).toBe(10_000)
+  })
+
+  it('starts with the chosen project and note', async () => {
+    const store = fakeStore()
+    const now = () => new Date('2026-10-31T09:00:00.000Z').getTime()
+    const { result } = renderHook(() => useRunningTimer({ store, now, tickMs: 0 }))
+    await waitFor(() => expect(result.current.status).toBe('stopped'))
+    await act(() => result.current.start({ projectId: 'p2', note: 'hi' }))
+    expect(result.current.status).toBe('running')
+    expect(result.current.entry).toMatchObject({ projectId: 'p2', note: 'hi', startedAt: '2026-10-31T09:00:00.000Z' })
+  })
+
+  it('on 409 adopts the entry running elsewhere and says so', async () => {
+    const store = fakeStore()
+    const { result } = renderHook(() => useRunningTimer({ store, tickMs: 0 }))
+    await waitFor(() => expect(result.current.status).toBe('stopped'))
+    store.failNext.create = conflict()
+    store.setRunning(open({ id: 'other' }))
+    await act(() => result.current.start({}))
+    expect(result.current.status).toBe('running')
+    expect(result.current.entry?.id).toBe('other')
+    expect(result.current.notice).toBe('already-running')
+    expect(result.current.error).toBeNull()
+  })
+
+  it('pause closes the entry; resume reopens with the same project and note', async () => {
+    const store = fakeStore(open())
+    const { result } = renderHook(() => useRunningTimer({ store, tickMs: 0 }))
+    await waitFor(() => expect(result.current.status).toBe('running'))
+    await act(() => result.current.pause())
+    expect(result.current.status).toBe('stopped')
+    expect(result.current.paused).toMatchObject({ projectId: 'p1', note: 'n' })
+    await act(() => result.current.resume())
+    expect(result.current.status).toBe('running')
+    expect(result.current.entry).toMatchObject({ projectId: 'p1', note: 'n' })
+    expect(result.current.entry?.id).not.toBe('r1')
+  })
+
+  it('stop forgets the paused interval, so there is nothing to resume', async () => {
+    const store = fakeStore(open())
+    const { result } = renderHook(() => useRunningTimer({ store, tickMs: 0 }))
+    await waitFor(() => expect(result.current.status).toBe('running'))
+    await act(() => result.current.stop())
+    expect(result.current.paused).toBeNull()
+  })
+
+  it('stop on a stale version re-reads and closes the fresh row once', async () => {
+    const store = fakeStore(open())
+    const { result } = renderHook(() => useRunningTimer({ store, tickMs: 0 }))
+    await waitFor(() => expect(result.current.status).toBe('running'))
+    store.failNext.update = stale()
+    store.setRunning(open({ version: 2 }))
+    await act(() => result.current.stop())
+    expect(result.current.status).toBe('stopped')
+    expect(result.current.error).toBeNull()
+  })
+
+  it('stop when another window already stopped it just refreshes to stopped', async () => {
+    const store = fakeStore(open())
+    const { result } = renderHook(() => useRunningTimer({ store, tickMs: 0 }))
+    await waitFor(() => expect(result.current.status).toBe('running'))
+    store.failNext.update = stale()
+    store.setRunning(null)
+    await act(() => result.current.stop())
+    expect(result.current.status).toBe('stopped')
+  })
+
+  it('surfaces other errors without losing the running entry', async () => {
+    const store = fakeStore(open())
+    const { result } = renderHook(() => useRunningTimer({ store, tickMs: 0 }))
+    await waitFor(() => expect(result.current.status).toBe('running'))
+    store.failNext.update = new Error('boom')
+    await act(() => result.current.stop())
+    expect(result.current.error?.message).toBe('boom')
+    expect(result.current.status).toBe('running')
+  })
+
+  it('reports each state change through onChange (tray sync)', async () => {
+    const store = fakeStore()
+    const onChange = jest.fn()
+    const { result } = renderHook(() => useRunningTimer({ store, tickMs: 0, onChange }))
+    await waitFor(() => expect(result.current.status).toBe('stopped'))
+    await act(() => result.current.start({ note: 'x' }))
+    expect(onChange).toHaveBeenLastCalledWith(expect.objectContaining({ id: expect.any(String), note: 'x' }))
+    await act(() => result.current.stop())
+    expect(onChange).toHaveBeenLastCalledWith(null)
+  })
+
+  it('resolves idle time through the planned writes, close before create', async () => {
+    const store = fakeStore(open())
+    const { result } = renderHook(() => useRunningTimer({ store, tickMs: 0 }))
+    await waitFor(() => expect(result.current.status).toBe('running'))
+    store.calls.length = 0
+    await act(() =>
+      result.current.resolveIdle({
+        idleSince: new Date('2026-10-31T10:00:00.000Z').getTime(),
+        now: new Date('2026-10-31T10:20:00.000Z').getTime(),
+        choice: { kind: 'assign', projectId: 'p2' },
+      }),
+    )
+    expect(store.calls.filter((c) => c !== 'find')).toEqual([
+      'update:{"endedAt":"2026-10-31T10:00:00.000Z"}',
+      'create:2026-10-31T10:20:00.000Z',
+      'create:open',
+    ])
+    expect(result.current.entry?.startedAt).toBe('2026-10-31T10:20:00.000Z')
+  })
+})

package/src/components/timer/index.ts

@@ -0,0 +1,20 @@
+export * from './interval-logic'
+export { useRunningTimer } from './useRunningTimer'
+export type { RunningTimer, StartInput, UseRunningTimerOptions } from './useRunningTimer'
+export { useIdleReturn } from './useIdleReturn'
+export type { IdlePrompt, IdleSignal, UseIdleReturnOptions } from './useIdleReturn'
+export { ProjectSwatch, NO_COLOR } from './ProjectSwatch'
+export { ColorPicker, PROJECT_COLORS } from './ColorPicker'
+export type { ColorPickerProps } from './ColorPicker'
+export { ProjectSelect } from './ProjectSelect'
+export type { ProjectOption, ProjectSelectProps } from './ProjectSelect'
+export { TimerBar } from './TimerBar'
+export type { TimerBarProps } from './TimerBar'
+export { IdlePromptDialog, formatIdle } from './IdlePromptDialog'
+export type { IdlePromptDialogProps } from './IdlePromptDialog'
+export { EntryFormDialog } from './EntryFormDialog'
+export type { EntryFormDialogProps, EntryFormValue } from './EntryFormDialog'
+export { EntryList } from './EntryList'
+export type { EntryListProps } from './EntryList'
+export { ProjectsDialog } from './ProjectsDialog'
+export type { ProjectsDialogProps, ProjectSave, ClientOption } from './ProjectsDialog'

package/src/components/timer/interval-logic.ts

@@ -0,0 +1,140 @@
+/**
+ * Pure logic for a running-interval timer: one open interval per owner,
+ * closed intervals everywhere else. Nothing here names time tracking beyond
+ * "started" and "ended"; a shift clock or a checkout ledger fits the same shape.
+ *
+ * PAUSE IS NOT A STATE. Pausing closes the interval; resuming opens a new one
+ * with the same project and note. Every row stays one closed interval, so a
+ * report is a sum of rows, and the store needs no attribute beyond the two
+ * timestamps (bd startsim-i2t09).
+ */
+
+export type EntryId = string | number
+
+/** One interval. `endedAt` null means it is running. Timestamps are UTC ISO-8601. */
+export interface TimedEntry {
+  id: EntryId
+  /** Row version for the store's optimistic write; opaque here. */
+  version?: number
+  startedAt: string
+  endedAt: string | null
+  projectId: EntryId | null
+  note: string
+  /**
+   * Store-owned passthrough for attributes the timer does not model. A backend whose
+   * update replaces the whole record must send them back or they are lost.
+   */
+  extra?: Record<string, unknown>
+}
+
+export interface NewEntry {
+  startedAt: string
+  endedAt: string | null
+  projectId?: EntryId | null
+  note?: string
+}
+
+export interface EntryPatch {
+  startedAt?: string
+  endedAt?: string | null
+  projectId?: EntryId | null
+  note?: string
+}
+
+/**
+ * What a backend must offer. `create` with `endedAt: null` is "start"; an
+ * `update` with `endedAt` set is "stop". A second open interval for the same
+ * owner must be refused with an error carrying `status: 409`.
+ */
+export interface IntervalStore {
+  findRunning(): Promise<TimedEntry | null>
+  create(input: NewEntry): Promise<TimedEntry>
+  update(entry: TimedEntry, patch: EntryPatch): Promise<TimedEntry>
+  remove(entry: TimedEntry): Promise<void>
+}
+
+export function isStatus(err: unknown, status: number): boolean {
+  return typeof err === 'object' && err !== null && (err as { status?: unknown }).status === status
+}
+
+export function elapsedMs(startedAt: string, nowMs: number): number {
+  return Math.max(0, nowMs - new Date(startedAt).getTime())
+}
+
+/** `h:mm:ss`, hours unbounded (a 100 hour interval reads `100:00:00`). */
+export function formatElapsed(ms: number): string {
+  const total = Math.max(0, Math.floor(ms / 1000))
+  const h = Math.floor(total / 3600)
+  const m = Math.floor((total % 3600) / 60)
+  const s = total % 60
+  return `${h}:${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`
+}
+
+const iso = (ms: number) => new Date(ms).toISOString()
+
+export type IdleChoice = { kind: 'keep' } | { kind: 'discard' } | { kind: 'assign'; projectId: EntryId }
+
+export type IdleOp =
+  | { kind: 'update'; patch: EntryPatch }
+  | { kind: 'create'; input: Required<Pick<NewEntry, 'startedAt' | 'endedAt'>> & { projectId: EntryId | null; note: string } }
+
+/**
+ * The ordered writes that resolve an idle window `[idleSince, now]` on the
+ * running `entry`. Order matters: the open-interval rule refuses a second open
+ * row, so the running row is always closed before a new one is created.
+ *
+ * `update` ops target `entry`. All timestamps are UTC ISO strings: the server
+ * compares them as text, so mixed offsets would sort wrong.
+ */
+export function planIdleResolution(input: {
+  entry: TimedEntry
+  idleSince: number
+  now: number
+  choice: IdleChoice
+}): IdleOp[] {
+  const { entry, idleSince, now, choice } = input
+  if (choice.kind === 'keep') return []
+  const startedInsideIdle = new Date(entry.startedAt).getTime() >= idleSince
+  const resumed: IdleOp = {
+    kind: 'create',
+    input: { startedAt: iso(now), endedAt: null, projectId: entry.projectId, note: entry.note },
+  }
+
+  if (startedInsideIdle) {
+    // Nothing before the idle window to keep: the entry itself is the idle time.
+    if (choice.kind === 'discard') return [{ kind: 'update', patch: { startedAt: iso(now) } }]
+    return [{ kind: 'update', patch: { endedAt: iso(now), projectId: choice.projectId } }, resumed]
+  }
+
+  const close: IdleOp = { kind: 'update', patch: { endedAt: iso(idleSince) } }
+  if (choice.kind === 'discard') return [close, resumed]
+  return [
+    close,
+    { kind: 'create', input: { startedAt: iso(idleSince), endedAt: iso(now), projectId: choice.projectId, note: '' } },
+    resumed,
+  ]
+}
+
+const pad = (n: number) => String(n).padStart(2, '0')
+
+/** ISO instant -> the `yyyy-mm-ddThh:mm` a datetime-local input shows (local zone). */
+export function toLocalInput(isoString: string): string {
+  const d = new Date(isoString)
+  if (Number.isNaN(d.getTime())) return ''
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}`
+}
+
+/** A datetime-local value -> UTC ISO, or null when blank or unparsable. */
+export function fromLocalInput(value: string): string | null {
+  if (!value) return null
+  const d = new Date(value)
+  return Number.isNaN(d.getTime()) ? null : d.toISOString()
+}
+
+export function validateRange(startedAt: string | null, endedAt: string | null): string | null {
+  if (!startedAt) return 'Enter a start time.'
+  if (endedAt && new Date(endedAt).getTime() <= new Date(startedAt).getTime()) {
+    return 'The end must be after the start.'
+  }
+  return null
+}

package/src/components/timer/useIdleReturn.ts

@@ -0,0 +1,49 @@
+'use client'
+
+import { useCallback, useEffect, useState } from 'react'
+
+/** The slice of the shell's idle events this hook reads (matches @startsimpli/desktop). */
+export type IdleSignal =
+  | { type: 'idle-start'; ts: number; idleSince: number; idleSeconds?: number }
+  | { type: 'idle-end'; ts: number; idleSince: number; idleSeconds?: number }
+  | { type: 'lock' | 'unlock' | 'suspend' | 'resume'; ts: number }
+
+export interface IdlePrompt {
+  /** When the idle stretch began (epoch ms). */
+  idleSince: number
+  /** When the user came back (epoch ms). */
+  until: number
+  seconds: number
+}
+
+export interface UseIdleReturnOptions {
+  /** Subscribe to idle events; undefined outside the desktop shell. */
+  subscribe: ((cb: (e: IdleSignal) => void) => () => void) | undefined
+  /** Epoch ms the running interval started; null when nothing is running. */
+  runningSince: number | null
+  /** Idle shorter than this is not worth asking about. */
+  minSeconds?: number
+}
+
+/**
+ * Turns the shell's idle-end event into a prompt, but only when an interval was
+ * running before the idle stretch began. The timer itself keeps running
+ * through idle; policy (keep, discard, assign) is applied by the caller.
+ */
+export function useIdleReturn({ subscribe, runningSince, minSeconds = 0 }: UseIdleReturnOptions) {
+  const [prompt, setPrompt] = useState<IdlePrompt | null>(null)
+
+  useEffect(() => {
+    if (!subscribe) return
+    return subscribe((e) => {
+      if (e.type !== 'idle-end') return
+      if (runningSince === null) return
+      const seconds = Math.round((e.ts - e.idleSince) / 1000)
+      if (seconds < minSeconds) return
+      setPrompt({ idleSince: e.idleSince, until: e.ts, seconds })
+    })
+  }, [subscribe, runningSince, minSeconds])
+
+  const dismiss = useCallback(() => setPrompt(null), [])
+  return { prompt, dismiss }
+}

package/src/components/timer/useRunningTimer.ts

@@ -0,0 +1,209 @@
+'use client'
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+import {
+  elapsedMs,
+  isStatus,
+  planIdleResolution,
+  type EntryId,
+  type IdleChoice,
+  type IntervalStore,
+  type TimedEntry,
+} from './interval-logic'
+
+export interface StartInput {
+  projectId?: EntryId | null
+  note?: string
+}
+
+export interface UseRunningTimerOptions {
+  store: IntervalStore
+  /** Clock, injectable for tests. */
+  now?: () => number
+  /** Re-render period while running; 0 disables the interval (tests). */
+  tickMs?: number
+  /** Called with the running entry (or null) whenever it changes, once loaded. Drives the tray. */
+  onChange?: (entry: TimedEntry | null) => void
+}
+
+export interface RunningTimer {
+  status: 'loading' | 'stopped' | 'running'
+  entry: TimedEntry | null
+  /** Milliseconds since the running entry started; 0 when stopped. */
+  elapsed: number
+  /** Set by pause(), cleared by stop() and resume(): what Resume would reopen. */
+  paused: TimedEntry | null
+  busy: boolean
+  error: Error | null
+  /** 'already-running': a start lost to an interval running elsewhere, which is now shown. */
+  notice: 'already-running' | null
+  start(input?: StartInput): Promise<void>
+  /** Closes the interval and keeps its project and note for resume(). */
+  pause(): Promise<void>
+  /** Closes the interval. */
+  stop(): Promise<void>
+  resume(): Promise<void>
+  refresh(): Promise<void>
+  resolveIdle(input: { idleSince: number; now: number; choice: IdleChoice }): Promise<void>
+  clearNotice(): void
+}
+
+/**
+ * The running interval, as the store sees it. The server is the authority: a
+ * start that loses the one-open-interval race (409) adopts the winner, a write
+ * against a moved row (412) re-reads once, and the tray/other windows are
+ * reconciled by refreshing on focus.
+ */
+export function useRunningTimer({ store, now = Date.now, tickMs = 1000, onChange }: UseRunningTimerOptions): RunningTimer {
+  const [entry, setEntry] = useState<TimedEntry | null>(null)
+  const [loaded, setLoaded] = useState(false)
+  const [paused, setPaused] = useState<TimedEntry | null>(null)
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState<Error | null>(null)
+  const [notice, setNotice] = useState<'already-running' | null>(null)
+  const [, setTick] = useState(0)
+  const entryRef = useRef(entry)
+  entryRef.current = entry
+  const onChangeRef = useRef(onChange)
+  onChangeRef.current = onChange
+
+  const refresh = useCallback(async () => {
+    try {
+      setEntry(await store.findRunning())
+    } catch (e) {
+      setError(e as Error)
+    } finally {
+      setLoaded(true)
+    }
+  }, [store])
+
+  useEffect(() => {
+    void refresh()
+  }, [refresh])
+
+  useEffect(() => {
+    if (!loaded) return
+    onChangeRef.current?.(entry)
+  }, [entry, loaded])
+
+  useEffect(() => {
+    if (!entry || tickMs <= 0) return
+    const id = setInterval(() => setTick((n) => n + 1), tickMs)
+    return () => clearInterval(id)
+  }, [entry, tickMs])
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return
+    const onFocus = () => void refresh()
+    window.addEventListener('focus', onFocus)
+    return () => window.removeEventListener('focus', onFocus)
+  }, [refresh])
+
+  const guarded = useCallback(async (fn: () => Promise<void>) => {
+    setBusy(true)
+    setError(null)
+    try {
+      await fn()
+    } catch (e) {
+      setError(e as Error)
+    } finally {
+      setBusy(false)
+    }
+  }, [])
+
+  /** Runs `fn` against the held row; on a stale version re-reads the running row and tries once more. */
+  const withFresh = useCallback(
+    async <T,>(fn: (e: TimedEntry) => Promise<T>): Promise<T | undefined> => {
+      const current = entryRef.current
+      if (!current) return undefined
+      try {
+        return await fn(current)
+      } catch (err) {
+        if (!isStatus(err, 412)) throw err
+        const fresh = await store.findRunning()
+        setEntry(fresh)
+        if (!fresh) return undefined
+        return fn(fresh)
+      }
+    },
+    [store],
+  )
+
+  const start = useCallback(
+    (input: StartInput = {}) =>
+      guarded(async () => {
+        setNotice(null)
+        try {
+          const created = await store.create({
+            startedAt: new Date(now()).toISOString(),
+            endedAt: null,
+            projectId: input.projectId ?? null,
+            note: input.note ?? '',
+          })
+          setEntry(created)
+        } catch (err) {
+          if (!isStatus(err, 409)) throw err
+          // Another window or the tray won the race: show what is running.
+          const winner = await store.findRunning()
+          setEntry(winner)
+          if (winner) setNotice('already-running')
+          else throw err
+        }
+      }),
+    [guarded, store, now],
+  )
+
+  const close = useCallback(
+    (keep: boolean) =>
+      guarded(async () => {
+        const closed = await withFresh((e) => store.update(e, { endedAt: new Date(now()).toISOString() }))
+        setPaused(keep && closed ? closed : null)
+        setEntry(null)
+      }),
+    [guarded, withFresh, store, now],
+  )
+  const stop = useCallback(() => close(false), [close])
+  const pause = useCallback(() => close(true), [close])
+
+  const resume = useCallback(async () => {
+    const from = paused
+    await start({ projectId: from?.projectId ?? null, note: from?.note ?? '' })
+    setPaused(null)
+  }, [start, paused])
+
+  const resolveIdle = useCallback(
+    (input: { idleSince: number; now: number; choice: IdleChoice }) =>
+      guarded(async () => {
+        const current = entryRef.current
+        if (!current) return
+        const ops = planIdleResolution({ entry: current, ...input })
+        try {
+          for (const op of ops) {
+            if (op.kind === 'update') await withFresh((e) => store.update(e, op.patch))
+            else await store.create(op.input)
+          }
+        } finally {
+          // Whatever landed, the server's view is the truth.
+          await refresh()
+        }
+      }),
+    [guarded, withFresh, store, refresh],
+  )
+
+  return {
+    status: !loaded ? 'loading' : entry ? 'running' : 'stopped',
+    entry,
+    elapsed: entry ? elapsedMs(entry.startedAt, now()) : 0,
+    paused,
+    busy,
+    error,
+    notice,
+    start,
+    pause,
+    stop,
+    resume,
+    refresh,
+    resolveIdle,
+    clearNotice: () => setNotice(null),
+  }
+}

package/src/utils/__tests__/xlsx.test.ts

@@ -0,0 +1,36 @@
+import * as XLSX from 'xlsx'
+import { csvFromRows } from '../csv'
+import { xlsxFromRows } from '../xlsx'
+
+const rows: (string | number)[][] = [
+  ['Period', 'Entries', 'Minutes', 'Earnings'],
+  ['2026-07', 3, 255, 195],
+  ['2026-08', 1, 60, 50],
+  ['Total', 4, 315, 245],
+]
+
+describe('xlsxFromRows', () => {
+  it('writes numbers as numbers so a spreadsheet can sum them', () => {
+    const wb = XLSX.read(xlsxFromRows(rows, { sheetName: 'Hours' }), { type: 'array' })
+    expect(wb.SheetNames).toEqual(['Hours'])
+    const back = XLSX.utils.sheet_to_json<(string | number)[]>(wb.Sheets.Hours, { header: 1 })
+    expect(back).toEqual(rows)
+    expect(typeof back[1][2]).toBe('number')
+  })
+
+  it('does not turn a formula-looking string into a formula', () => {
+    const wb = XLSX.read(xlsxFromRows([['=1+1', '@x']]), { type: 'array' })
+    const cell = wb.Sheets[wb.SheetNames[0]].A1
+    expect(cell.t).toBe('s')
+    expect(cell.f).toBeUndefined()
+    expect(cell.v).toBe('=1+1')
+  })
+
+  it('agrees with the CSV writer on every cell', () => {
+    const wb = XLSX.read(xlsxFromRows(rows), { type: 'array' })
+    const fromXlsx = XLSX.utils.sheet_to_csv(wb.Sheets[wb.SheetNames[0]], { rawNumbers: true })
+    expect(fromXlsx.trim().split('\n').map((l) => l.split(','))).toEqual(
+      csvFromRows(rows.map((r) => r.map(String))).trim().split('\r\n').map((l) => l.split(',')),
+    )
+  })
+})