85 lines
4.9 KiB
Markdown
85 lines
4.9 KiB
Markdown
# Active Reading Clock
|
|
|
|
Current policy: relaxed personal estimates, implemented 2026-10-06. This is not an
|
|
anti-cheat system, proof of comprehension, or a basis for competitive rewards.
|
|
Enable it in User → Reading time. Disabled means no clock requests.
|
|
|
|
## What counts
|
|
|
|
Each chapter visit measures foreground, loaded-page viewing time. After viewing
|
|
**at least 60% of eligible pages**, rounded up, the whole visit's active time counts,
|
|
including time before reaching that threshold. It continues counting through the
|
|
rest of the visit and is saved periodically and when leaving the reader.
|
|
|
|
- There is **no pages-per-second ceiling** and no skimming penalty.
|
|
- A loaded image needs **100 ms cumulative visible exposure**. Flow exposure uses
|
|
10% of the smaller of page/viewport area and samples scroll positions plus a
|
|
50 ms timer. This detects brief views; it does not assess reading speed.
|
|
- Only actually observed pages count. A scrollbar/slider jump does not credit
|
|
all pages between the starting position and destination.
|
|
- Hidden covers/extras are excluded from the denominator.
|
|
- Source versions have separate visit coverage; qualifying time combines into
|
|
existing chapter totals without changing reading identities.
|
|
- Below-60% visits remain bounded diagnostic drafts, excluded from Reading Story,
|
|
first/last-read duration, reread counts and chapter headline totals.
|
|
- New navigation starts a fresh visit. Old coverage does not qualify later picture
|
|
lookups. Separate sub-60% visits are not combined. Back/forward-cache restoration
|
|
continues the same visit.
|
|
|
|
Example: view 12 of 20 pages, then leave → all active time from that visit counts.
|
|
Jump to page 19, dwell, leave → no new reading total. Historical times are retained;
|
|
this update neither deletes old measurements nor invents times for missed reads.
|
|
|
|
Intent cannot be inferred perfectly: slowly searching most of a chapter can look
|
|
like reading. This rule filters quick-search-and-one-picture visits without
|
|
penalizing honest fast readers. Ordinary read/unread progress is independent.
|
|
|
|
## Pauses and display
|
|
|
|
Pause when hidden/unfocused; resume on reader input after returning. Pause after
|
|
**30 seconds** without activity (updated at the user's request on 2026-10-06). The first loaded page can start
|
|
without an extra click. Mouse/pen motion, wheel, touch movement, momentum scrolling
|
|
and keyboard controls—including held Up/Down arrows—refresh reader activity.
|
|
|
|
Loading wait stays separate. An unloaded neighbour no longer pauses the clock if
|
|
another visible image is readable. Failed/unloaded images do not earn coverage.
|
|
An end card pauses time. Other reader tabs/devices coordinate to avoid accidental
|
|
duplicate clocks; this is not an anti-cheat score.
|
|
|
|
The toolbar shows **this visit's** time. Its panel shows pages viewed, the 60%
|
|
requirement, whether the visit counts, saved chapter total, loading wait and
|
|
pause/save-pending state. “Verified”, “rejects” and “skimming” labels are removed.
|
|
|
|
## Reliable saves and compatibility
|
|
|
|
New clients POST cumulative snapshots to authenticated `/api/reading/visit` every
|
|
10 seconds, on attention changes, and using `sendBeacon` (keepalive fallback) on
|
|
`pagehide`. Final snapshots dispatch even with an ordinary request in flight.
|
|
Visit ID plus increasing sequence makes retries/out-of-order packets idempotent.
|
|
Delayed saves avoid the legacy 12-second packet truncation. Final saves don't
|
|
reclaim the next chapter's lease, nor do stale pulses reclaim an exited lease.
|
|
|
|
First/last duration keeps growing after qualification until departure. Late finals
|
|
update their own receipt, not a newer visit. The latest eight visit receipts are
|
|
retained per chapter; extremely old delayed requests after eviction are outside
|
|
this bounded retry window. There is no durable offline queue: closing an offline
|
|
tab or a browser/OS crash can still lose undelivered time. “Save pending” is explicit.
|
|
|
|
Legacy `/api/reading/pulse` remains for already-open old readers. Existing records
|
|
and totals are retained. Reload open readers for this policy. On code rollback the
|
|
separate new endpoint returns 404 instead of interpreting cumulative totals as
|
|
legacy deltas. Refresh open readers after rollback as well.
|
|
|
|
## Privacy and verification
|
|
|
|
Only chapter/version IDs, visit/sequence IDs, cumulative active/loading/input-type
|
|
times, viewed page indexes and exit flags are sent. No coordinates, key contents,
|
|
recordings, screenshots or raw event stream are saved. Exposure geometry stays
|
|
local. History is private to the user and existing export/reset controls remain.
|
|
|
|
`test/reading-visits.test.js` covers thresholds, historical preservation, fast
|
|
slices, lookup exclusion, attention/loading, late/duplicate snapshots and delayed
|
|
delivery. `node tools/test-compose.js --reading-ui` adds actual headless Edge
|
|
mobile-layout QA with disposable users/generated images/isolated storage. It does
|
|
not observe production readers or query image hosters.
|