Skip to content

refactor: engine owns its state (T6a) (@miodec) - #8598

Open
Miodec wants to merge 11 commits into
masterfrom
t6a-engine-state
Open

Miodec wants to merge 11 commits into
masterfrom
t6a-engine-state

Conversation

@Miodec

@Miodec Miodec commented Nov 19, 2026

Copy link
Copy Markdown
Member

Roadmap step T6a: the test engine owns its state. test-logic stays the glue and calls engine commands at the same moments it set the old flags.

Summary

 src/ts/test/
+├── engine/
+│   ├── state.ts          # signals + small commands (phase, word index, live stats, frozen log…)
+│   ├── commands.ts       # lifecycle: start / finish(failReason?) / reset / restart / endRestart / measureWordBurst
-├── test-words.ts
+│   ├── test-words.ts     # read-only words + pushWord / resetWords
-├── test-timer.ts
+│   ├── test-timer.ts     # timer core only: tick, running, slow-timer signals
+│   ├── input-type.ts     # was input/helpers/
-├── events/
+│   └── events/           # EventLog
+├── timer-effects.ts      # time warning, layoutfluid, low fps: effects on the timer signals
 └── test-logic.ts         # glue: calls Engine.*
 src/ts/input/helpers/
+└── test-event-code.ts    # getTestEventCode / keysToTrack (input filters untracked keys)

State moved out of states/test:

- isTestActive() / isTestFinished() / isTestRestarting()
+ getPhase(): "idle" | "active" | "finished" | "restarting"
+ getFailReason(): string | null          # a fail is finished + reason
+ isResultScreen()                         # finished, or the result fading out (states; T6b drops isResultFadingOut)
- increase/decreaseActiveWordIndex
+ increment/decrementActiveWordIndex, resetActiveWordIndex
- getLastEventLog
+ getFrozenLog (finish freezes it, test-logic publishes it with the result: T6c)
- currentLiveStats (written by input + timer)
+ liveStats: timer sets wpm/raw/seconds; acc/burst are memos flushed once per rAF after logTestEvent
- __nonReactive
+ loadInputLayout() / loadKeymapLayout()

Lint: new engine override (no UI, input, test-logic, funbox, custom-text imports; no DOM globals). Custom-text/funbox reads in the timer and EventLog context carry T6b disables.

Intended deviations (in the spec):

  • live acc/burst update one frame after the keystroke (never render synchronously from input)
  • live acc is always rounded to 2 decimals (the timer tick used to write it unrounded)

Evidence

  • Lint + typecheck clean; 1881 tests pass. New __tests__/test/engine/commands.spec.ts (phases, fail reason, frozen log published separately, force-release, word index, bail out, live stats flush on the next frame).
  • Browser (dev):
    • words test active → finished; time 15 with mini live stats; layoutfluid switches at 5s/10s; zen
    • restart from result: restarting with the result still fading out, TestConfig hidden until it's gone (same as master)
    • min acc 100% → result shows "failed (min accuracy)", cleared by restart
  • Not exercised: slow-timer fail; time warning sound by ear (same tick effect as layoutfluid).

Merge Danger

Door: two-way

Pure refactor, revertable in one commit; no data or schema changes.

Blast Radius: test-page

Every typing test runs through the moved state: phase guards on input/router/restart, live stats, the result (frozen log, fail reason). A regression would show as a stuck restart, missing live stats or a wrong result screen.

🤖 Generated with Claude Code

Copilot AI balanced review requested due to automatic review settings November 19, 2026 09:22
@monkeytypegeorge monkeytypegeorge added frontend User interface or web stuff local dev Related to the build process or dependencies docs Related to Markdown files and documentation labels Nov 19, 2026
@github-actions github-actions Bot added the waiting for review Pull requests that require a review before continuing label Nov 19, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The change still has an open documentation inconsistency: in docs/specs/solid-monkeytype/roadmap.md line 19 the roadmap checklist marks T6a as done in text while leaving it unchecked, conflicting with the detailed table below.

1 open issue
What changed in this PR

Refactors the typing-test runtime so the test engine owns core state (phase, word index, timer signals, live stats, and frozen event log), while existing glue/UI layers are rewired to call engine commands and read engine-owned signals.

Changes:

  • Introduce test/engine/ state + lifecycle commands, with DOM-free EventLog and timer core modules.
  • Move timer side effects into test/timer-effects.ts and update input/router/UI/controllers to use phase/result predicates and frozen log APIs.
  • Update lint rules, specs, and tests to match the new engine architecture and key-tracking split.
File Description
frontend/​src/​ts/​test/​words-history.ts Updates result/history interactions to use engine result-screen predicates and the frozen event log instead of legacy test flags.
frontend/​src/​ts/​test/​words-generator.ts Repoints word generation to consume the new engine-owned test words module.
frontend/​src/​ts/​test/​weak-spot.ts Updates weak-spot logic to import live-cache/stat utilities from the relocated engine events modules.
frontend/​src/​ts/​test/​timer-effects.ts Adds timer-side effects (time warning, layoutfluid, low-FPS toggles) as reactive effects driven by timer signals.
frontend/​src/​ts/​test/​test-logic.ts Rewires the test orchestration layer to call engine lifecycle commands, publish frozen logs, and use phase-based guards.
frontend/​src/​ts/​test/​practise-words.ts Updates practice-words mode to use engine words/events and read results from the frozen log APIs.
frontend/​src/​ts/​test/​pace-caret.ts Switches caret pacing and gating logic to rely on engine phase/result-screen checks and engine word index state.
frontend/​src/​ts/​test/​layout-emulator.ts Replaces legacy non-reactive layout access with engine-provided layout load helpers.
frontend/​src/​ts/​test/​funbox/​funbox-functions.ts Updates funbox helpers to use engine-owned words and active word index state.
frontend/​src/​ts/​test/​engine/​test-words.ts Introduces an engine-owned words module exposing a read-only API plus controlled mutation helpers (push/reset/etc.).
frontend/​src/​ts/​test/​engine/​test-timer.ts Moves timer core into the engine with tick/running/slow-timer signals and writes timer-driven live stats into engine state.
frontend/​src/​ts/​test/​engine/​state.ts Adds engine-owned reactive state for phase, word index, fail reason, frozen log, and live stats used across the test page.
frontend/​src/​ts/​test/​engine/​input-type.ts Adds shared helpers/types for supported InputEvent.inputType values used by engine/input modules.
frontend/​src/​ts/​test/​engine/​events/​types.ts Relocates and updates EventLog type definitions and related imports for the new engine module layout.
frontend/​src/​ts/​test/​engine/​events/​timing-stats.ts Adds a pure timing-stats module for computing timing metrics from EventLog data.
frontend/​src/​ts/​test/​engine/​events/​stats.ts Updates event stats computation to the new engine events module structure and import paths.
frontend/​src/​ts/​test/​engine/​events/​live-cache.ts Moves the live-cache implementation under engine events and updates references/tests accordingly.
frontend/​src/​ts/​test/​engine/​events/​helpers.ts Refactors engine event helpers to focus on pure event derivations after moving keycode filtering out to the input layer.
frontend/​src/​ts/​test/​engine/​events/​data.ts Moves the EventLog store/pressed-key tracking into the engine and aligns logging behavior with input-layer filtering.
frontend/​src/​ts/​test/​engine/​commands.ts Adds engine lifecycle commands (start/finish/reset/restart/endRestart/measureWordBurst) to own state transitions.
frontend/​src/​ts/​states/​test.ts Removes core test state from UI states and adds higher-level predicates/helpers (e.g., result-screen and layout loaders) backed by engine state.
frontend/​src/​ts/​states/​result.ts Updates result state integration to align with the engine frozen log and result-screen semantics.
frontend/​src/​ts/​states/​live-stats.ts Switches live-stats state to read from engine live stats and engine phase rather than being written by input/timer directly.
frontend/​src/​ts/​states/​hotkeys.ts Repoints hotkeys-related test facts/signals to the engine-owned state.
frontend/​src/​ts/​states/​event-log-viewer.ts Updates the event log viewer state to use engine EventLog types and sources.
frontend/​src/​ts/​states/​connection.ts Adjusts connection/offline UI gating to use engine phase checks instead of legacy test-active flags.
frontend/​src/​ts/​router/​create-router.ts Updates navigation guards to rely on engine phase (including restarting/result-screen behavior).
frontend/​src/​ts/​input/​listeners/​input.ts Updates the main input listener to use engine input-type helpers, engine phase guards, and engine words/events modules.
frontend/​src/​ts/​input/​listeners/​composition.ts Rewires composition handling to use engine phase/word index and engine event logging.
frontend/​src/​ts/​input/​hotkeys/​quickrestart.ts Updates quick-restart behavior to read needed test facts from engine-owned state.
frontend/​src/​ts/​input/​helpers/​word-navigation.ts Updates word navigation to use engine word index setters and engine burst measurement utilities.
frontend/​src/​ts/​input/​helpers/​test-event-code.ts Adds input-layer key mapping and a tracked-keys set used to filter which keys are logged.
frontend/​src/​ts/​input/​helpers/​after-input.ts Removes synchronous live-stat writes after input and defers to engine-owned live-stats flushing behavior.
frontend/​src/​ts/​input/​handlers/​keyup.ts Filters keyup logging via keysToTrack and routes logged events to the engine logger.
frontend/​src/​ts/​input/​handlers/​keydown.ts Filters keydown logging via keysToTrack and updates bailout/restart logic to call engine commands.
frontend/​src/​ts/​input/​handlers/​insert-text.ts Updates insert-text handling to use engine phase/words/current-input state and engine input-type helpers.
frontend/​src/​ts/​input/​handlers/​delete.ts Updates delete handling to use engine modules for word index/current input and event logging.
frontend/​src/​ts/​input/​handlers/​before-insert-text.ts Updates before-insert-text guards to rely on engine phase and engine slow-timer signals.
frontend/​src/​ts/​input/​handlers/​before-delete.ts Updates before-delete guards and word lookups to use engine phase and engine word-input helpers.
frontend/​src/​ts/​elements/​monkey-power.ts Updates monkey-power behavior to consume the engine timer slow-timer signal.
frontend/​src/​ts/​elements/​confetti.ts Updates confetti behavior to consume the engine timer slow-timer signal.
frontend/​src/​ts/​dev/​expose.ts Updates dev-exposed helpers to reference engine event/current-input sources.
frontend/​src/​ts/​controllers/​pw-ad-controller.ts Updates ad controller gating to use the engine-backed result-screen predicate.
frontend/​src/​ts/​controllers/​challenge-controller.ts Updates challenge controller gating/guards to use engine phase (including restarting).
frontend/​src/​ts/​controllers/​ad-controller.ts Updates ad refresh suppression logic to use engine phase checks.
frontend/​src/​ts/​console-globals.ts Updates console/debug globals to expose engine frozen logs and engine timer/event-log builders.
frontend/​src/​ts/​config/​setters.ts Updates configuration setters that gate on test state to use engine phase rather than legacy flags.
frontend/​src/​ts/​components/​pages/​test/​WordsInput.tsx Updates WordsInput focus/scroll and interaction guards to use engine phase/result-screen checks.
frontend/​src/​ts/​components/​pages/​test/​words-layout.ts Updates words layout rendering/behavior to use engine phase/result predicates and engine slow-timer state.
frontend/​src/​ts/​components/​pages/​test/​TestPage.tsx Updates page-level test flow to derive UI state from engine phase and result-screen semantics.
frontend/​src/​ts/​components/​pages/​test/​TestConfig.tsx Updates TestConfig visibility/disabled states to follow engine phase and result-screen/restarting rules.
frontend/​src/​ts/​components/​pages/​test/​result/​TestResult.tsx Updates the result view to read event/log data from the engine frozen log instead of mutable live state.
frontend/​src/​ts/​components/​pages/​test/​result/​ResultWordsHistory.tsx Updates result words-history rendering/hover gating to use result-screen checks and engine event stats/types.
frontend/​src/​ts/​components/​pages/​test/​result/​ResultMainStats.tsx Updates result main stats to import and compute from engine event stats/types modules.
frontend/​src/​ts/​components/​pages/​test/​result/​ResultChart.tsx Updates result chart highlighting/tooltips to use engine types/stats and the frozen event log.
frontend/​src/​ts/​components/​pages/​test/​result/​replay.ts Updates replay generation to consume the engine frozen log and engine event helpers/stats/types.
frontend/​src/​ts/​components/​pages/​test/​Premid.tsx Updates Premid presence calculations to use engine live stats (e.g., seconds remaining).
frontend/​src/​ts/​components/​pages/​test/​Monkey.tsx Updates Monkey display/animation conditions to use engine phase and engine live stats.
frontend/​src/​ts/​components/​pages/​test/​modes-notice/​TestModesNotice.tsx Updates modes notice logic to read word facts from engine state.
frontend/​src/​ts/​components/​pages/​test/​Keymap.tsx Updates keymap UI logic to read word facts from engine state.
frontend/​src/​ts/​components/​pages/​test/​caret.ts Updates caret rendering logic to import words/index state from the engine modules.
frontend/​src/​ts/​components/​modals/​EventLogViewerModal.tsx Updates the event log viewer modal to load from the engine frozen log and use engine timing-stats/types modules.
frontend/​src/​ts/​components/​modals/​DevOptionsModal.tsx Updates dev options wiring to import slow-timer controls/state from the engine timer module.
frontend/​src/​ts/​commandline/​lists/​result-screen.ts Updates result-screen commandline actions to use engine result-screen predicates and the frozen log.
frontend/​src/​ts/​commandline/​lists/​bail-out.ts Updates bail-out commandline action to call the engine bailout/finish command path.
frontend/​src/​ts/​commandline/​lists.ts Updates commandline list commands to use engine frozen-log access instead of the previous last-event-log API.
frontend/​.oxlintrc.json Adds engine-specific lint restrictions to enforce module boundaries (no UI/input/DOM imports inside engine).
frontend/​__tests__/​test/​engine/​test-words.spec.ts Updates engine words tests to match the new read-only API and mutation helpers.
frontend/​__tests__/​test/​engine/​events/​stats.spec.ts Updates event stats tests/mocks for the engine events module split and new import paths.
frontend/​__tests__/​test/​engine/​events/​live-cache.spec.ts Updates live-cache tests to use the relocated engine events implementation and updated dependencies.
frontend/​__tests__/​test/​engine/​events/​helpers.spec.ts Refactors helper tests to align with engine helpers after moving keycode mapping out of the engine.
frontend/​__tests__/​test/​engine/​events/​data.spec.ts Updates EventLog data-store tests for the engine relocation and the input-layer key filtering split.
frontend/​__tests__/​test/​engine/​commands.spec.ts Adds/updates tests covering engine lifecycle commands, phase transitions, fail reason, and frozen log publication behavior.
frontend/​__tests__/​root/​config.spec.ts Updates config tests that depend on test state to observe engine phase instead of legacy test flags.
frontend/​__tests__/​input/​helpers/​test-event-code.spec.ts Adds tests for the new input-layer key mapping and tracked-keys filtering behavior.
frontend/​__tests__/​input/​handlers/​insert-text.spec.ts Updates insert-text handler tests to use the new engine modules (phase/words/events/input-type).
frontend/​__tests__/​input/​after-input-words.spec.tsx Updates after-input words tests to use engine word/index APIs and updated reset behavior.
frontend/​__tests__/​components/​pages/​test/​result/​ResultButtons.spec.tsx Updates result button tests to set required word facts via the engine state APIs.
frontend/​__tests__/​__harness__/​test-page.tsx Updates the test-page harness to observe engine phase/live stats and the new restart/result flow.
frontend/​__tests__/​__harness__/​app-shell.tsx Updates the app-shell harness to control and assert test flow via engine phase rather than legacy flags.
docs/​specs/​solid-monkeytype/​spec.md Updates the spec documentation to reflect the new engine-owned state model, phases/fail-reason semantics, and timer-effects split.
docs/​specs/​solid-monkeytype/​roadmap.md Updates roadmap documentation for T6a completion notes and related architectural references.

Review effort: Balanced
Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.

Comment thread docs/specs/solid-monkeytype/roadmap.md Resolved
Miodec and others added 9 commits November 19, 2026 15:27
Engine state moves to test/engine: phase (replaces the active/finished/
restarting flags), active word index, words (read-only, written through
commands), timer, live stats, bail out, word facts and the frozen log.
Lifecycle commands in engine/commands; test-logic calls them at the old
moments. Result-screen readers use isResultScreen(), which also covers
restart's result fade-out. Live acc/burst are memos flushed once per
frame. Timer UI side effects become effects in test/timer-effects.ts.
Key-code helpers move to input; states/test drops __nonReactive.
Engine lint rule added.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reverts 3fa07e8.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…Index (T6a)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Miodec added a commit that referenced this pull request Nov 19, 2026
File moves only, plus import path updates: test/events/, test-words,
test-timer and input/helpers/input-type move to test/engine/, with
their specs. Split out of #8598 (T6a: engine owns its state) to keep
its diff to the real changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Miodec and others added 2 commits November 19, 2026 15:36
The type becomes TestPhase; the test-page harness's own phase type is
now PagePhase.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Related to Markdown files and documentation frontend User interface or web stuff local dev Related to the build process or dependencies waiting for review Pull requests that require a review before continuing

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants