Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
ff6b61c
refactor: joining script dots via CSS, break joining deleted (T2)
Miodec Nov 9, 2026
021177a
docs: tick T2 in the Solid roadmap, record joining-script dot deviations
Miodec Nov 9, 2026
5717ebf
docs: link the T2 PR in the Solid roadmap
Miodec Nov 9, 2026
443361a
refactor: Words drives the caret and pace caret (T3)
Miodec Nov 9, 2026
234499a
docs: tick T3 in the Solid roadmap, record caret deviations
Miodec Nov 9, 2026
e42aebf
refactor: caret elements as a local Words component
Miodec Nov 9, 2026
1655e75
refactor: set the words input focus signal directly
Miodec Nov 9, 2026
3e99f99
refactor: drop isInputElementFocused for the words input focus signal
Miodec Nov 9, 2026
6812960
refactor: one caret list for the line jump and tape scroll handoff
Miodec Nov 9, 2026
ce9bfbd
refactor: rename the Words caret component to Caret, kind to id
Miodec Nov 9, 2026
e360aa6
refactor: caret follow-ups from the T3 review
Miodec Nov 10, 2026
b05e717
docs: link the T3 PR in the Solid roadmap
Miodec Nov 10, 2026
a9c1aa1
Merge branch 'master' into refactor/caret-boundary
Miodec Nov 11, 2026
2efab82
fix: clamp the pace caret animation duration to zero when a frame is …
Miodec Nov 11, 2026
37f34c2
refactor: caret style as data-ui-variant, caret CSS targets data-ui-*…
Miodec Nov 11, 2026
81534f5
refactor: word registry private to Words (T4) (@miodec)
Miodec Nov 11, 2026
2efc71c
docs: link T4 commit in roadmap
Miodec Nov 11, 2026
3dc60c0
docs: link the T4 PR in the Solid roadmap
Miodec Nov 11, 2026
d6e3289
docs: elements only through refs (Q31), add T4b letter refs to the ro…
Miodec Nov 11, 2026
97cdf46
Merge branch 'master' into refactor/word-registry-private
Miodec Nov 17, 2026
9d34208
refactor: letter refs through the word registry (T4b)
Miodec Nov 17, 2026
42a2acf
docs: link T4b PR in roadmap
Miodec Nov 17, 2026
56efc98
Merge remote-tracking branch 'origin/master' into refactor/word-regis…
Miodec Nov 17, 2026
963ba86
Merge branch 'refactor/word-registry-private' into refactor/letter-refs
Miodec Nov 17, 2026
01ed110
refactor: word elements handle, carets look words up by index (T4b)
Miodec Nov 17, 2026
6279530
refactor: name the caret's registry wordRegistry
Miodec Nov 17, 2026
bf56a3c
refactor: rename WordElements to MountedWord
Miodec Nov 17, 2026
4b64ad5
refactor: get prefix on MountedWord's letter reads
Miodec Nov 17, 2026
6a56fa8
docs: say why dev and tests keep a letter selector
Miodec Nov 17, 2026
40de397
Merge remote-tracking branch 'origin/master' into refactor/letter-refs
Miodec Nov 18, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/specs/solid-monkeytype/roadmap.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Each step can start once the previous step's **bold** items are done. Everything
- [ ] 2. **TH1** test-page harness, then **T1** `data-ui-*` on words and letters. Alongside: U2, U3, U4 (after U1), C2, C3.
- [x] 3. **T2** joining-script dots. Alongside: EP3.
- [x] 4. **T3** caret boundary. Then L3 and L12 can start.
- [ ] 5. **T4** word registry private (done) → **T4b** letter refs.
- [x] 5. **T4** word registry private → **T4b** letter refs.
- [ ] 6. **T5** delete test-ui (needs EP1, EP2, L1, L2 from step 1).
- [ ] 7. **T6a** engine state → **T6b** restart via flag and **T6c** finish split (these two in parallel).
- [ ] 8. **T7** drop the page-mount workaround (needs L3, L4, L5). Alongside: C4, U6.
Expand Down Expand Up @@ -87,7 +87,7 @@ Serial; each step needs the previous one. Verify each in the browser (`__mt.chec
| [x] | T2 | M · PR | **Break joining** computed in the layout pass, rendered as reactive class/style on Word; delete the break-joining module's DOM writes. Done in [#8562](https://github.com/monkeytypegame/monkeytype/pull/8562): replaced instead of moved. Joining-script letters stay inline under the dots typed effect and draw their own dot (CSS only, a `::before` copy from `data-char` runs the shrink), so nothing is measured; the break-joining module, its layout calls and config effects are deleted, and Word uses `cn` (no outside class writes left). Deviations in the spec | T1, TH1 | The only outside writes into Word elements |
| [x] | T3 | L · PR | **Caret boundary**: Words is the only thing that drives the caret and pace caret; line-jump/tape-scroll handoff becomes internal to Words; pace-caret timing moves to a DOM-free module outputting a word/letter target; caret and pace caret get `data-ui-element`. Caret and words layout read the typed input from the render store (input writes it alongside the EventLog), not the engine's `getCurrentInput()`. Decide the caret internals here (reactive, imperative handle, or a mix). Fix the tape offset for a word whose direction differs from the test's: after EP3 the caret is still up to ~105px off its letter (measured; ~194px seen in word tape), mixed custom text and polyglot only. Done in [#8563](https://github.com/monkeytypegame/monkeytype/pull/8563): Words renders `#caret`/`#paceCaret` (`data-ui-element` `caret`/`paceCaret`) with reactive style class, visibility (`isWordsInputFocused`, set by WordsInput; hidden from `isResultCalculating` on) and blinking (focus mode); movement stays on the `Caret` handle (`components/pages/test/caret.ts`, was `elements/caret.ts`) owned by the words layout. `test/caret.ts` deleted; `test/pace-caret.ts` is DOM-free, exporting `paceCaretTarget`. The tape's letter shift is shared (`getTapeLetterShift`); a locked caret in a word running against the test places itself from the tape anchor. Monkey power still reads `#caret` from the DOM (L3); the dev handle finds the caret by `data-ui-element`. Caret style is also `data-ui-variant`; `caret.scss` and the bundled theme and crt funbox caret CSS target `data-ui-*` (style classes kept for legacy themes). Deviations in the spec | T2 | Outside caret callers (test-ui, timer, focus, WordsInput) |
| [x] | T4 | S · commit | **Word registry private** to Words; only the synchronous overflow check stays exported. Done in [#8567](https://github.com/monkeytypegame/monkeytype/pull/8567): `createWordRegistry()` per Words instance (`components/pages/test/word-registry.ts`), Word/line breaks register via a prop, `Caret.goTo` takes the word element; `states/word-elements.ts` deleted, `LETTER_SELECTOR` in `components/pages/test/selectors.ts` | T3 | The public word-elements bridge |
| [ ] | T4b | M · PR | **Letter refs**: each Word keeps its letter elements, filled by WordLetter callback refs and read through the word registry (eg. `registry.getLetters(i)`); caret, words layout and TypoHints use them instead of selector queries; caret debug marking becomes a reactive attribute on WordLetter (drops its document queries); the overflow probe inserts its temporary letters after the last ref. Delete `LETTER_SELECTOR` (`dev/` and tests may keep a local selector). Spec Q33 | T4 | The test words' selector queries |
| [x] | T4b | M · PR | **Letter refs**: each Word keeps its letter elements, filled by WordLetter callback refs and read through the word registry (eg. `registry.getLetters(i)`); caret, words layout and TypoHints use them instead of selector queries; caret debug marking becomes a reactive attribute on WordLetter (drops its document queries); the overflow probe inserts its temporary letters after the last ref. Delete `LETTER_SELECTOR` (`dev/` and tests may keep a local selector). Spec Q33. Done in [#8593](https://github.com/monkeytypegame/monkeytype/pull/8593): Word keeps its letter refs (WordLetter `ref` prop, trimmed on `<Index>` cleanup) behind a `MountedWord` handle (`el`, `getLetter(i)`, `getLetterCount()`) it registers; `registry.getWord(i)` returns that handle, read by the tape letter shift, the newline width and the overflow probe; TypoHints gets `getLetter(i)` from Word. Carets are built with the registry: `Caret.goTo` takes indexes only (no `wordEl`). Letter helpers take `HTMLElement`. Caret debug: `caretDebugTarget` signal (target and visible fallback letter) set by the pace caret, WordLetter adds the `debugCaret*` classes. `selectors.ts` deleted; `dev/expose.ts` and tests keep a local selector | T4 | The test words' selector queries |
| [ ] | T5 | L · PR | **Delete test-ui**: sound/keymap/monkey-power triggers become effects or input-layer calls; autofocus moves to WordsInput; fades move to TestPage, as does the pre-test scroll to the test block (the focus flow keeps requesting Words' active-line recenter during a test). Add the **input-layer lint rule** (no component/UI imports) | T4b, EP1, EP2, L1, L2 | The glue module test-logic and input call |
| [ ] | T6 | split | **Engine split**, in three PRs: | T5 | test-logic ↔ UI coupling |
| [ ] | T6a | L · PR | Engine owns its state module (phase, active word index, words, timer, live stats); commands start/restart/finish/fail; the general test state keeps only UI state; drop its `__nonReactive` (layout emulator and keydown read engine/UI state directly). The engine owns the EventLog: event arrays, pressed keys, `logTestEvent` as a command; derived signals for current input, live stats and the frozen log (replaces `lastEventLog` in the test state module); key-code helpers (`getTestEventCode`, `keysToTrack`) move to input. Add the **engine lint rule** (no UI/input/DOM; data layer allowed) | T5 | |
Expand Down
2 changes: 1 addition & 1 deletion docs/specs/solid-monkeytype/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -185,7 +185,7 @@ Users should see no behaviour change, except where a bug at today's seams disapp
### Typing test: render layer

- The words render store, fed by the shared per-frame flush buffer, is the only input to Words, Word, WordLetter and TypoHints, including the typed input that layout and the caret position from.
- **Words owns all layout**: after each flush it runs one layout pass: line jump, tape scroll, input positioning and caret updates. Joining-script dots (dots typed effect) are CSS only: letters stay inline, so nothing is measured and nothing writes into Word. The word-element registry is private to Words: Words creates one per instance, its Word and line breaks register through a callback prop, and its layout hands the caret the word element. From T4b it also holds each word's letter elements, filled by WordLetter callback refs; caret debug marking is a reactive attribute on WordLetter. Only the overflow check is exported, reading the mounted Words' registry.
- **Words owns all layout**: after each flush it runs one layout pass: line jump, tape scroll, input positioning and caret updates. Joining-script dots (dots typed effect) are CSS only: letters stay inline, so nothing is measured and nothing writes into Word. The word-element registry is private to Words: Words creates one per instance, its Word and line breaks register through a callback prop, and it also holds each word's letter elements: Word registers a handle (`el`, `getLetter(i)`, `getLetterCount()`) over the letters its WordLetter callback refs fill (TypoHints gets `getLetter(i)` from Word as a prop). The layout builds the carets with the registry, so they look words up by index. Caret debug marking is reactive on WordLetter: its classes follow a target signal the pace caret sets. Only the overflow check is exported, reading the mounted Words' registry.
- **Words keeps the active line in view** as part of that layout pass: during a test, when the words wrapper is taller than the window, it scrolls the window to the active word (down only while typing, both ways when recentering after a re-layout or on request). The focus flow asks for a recenter through a request signal. Before the test, TestPage keeps the test block in view.
- **Carets: Words renders and drives both.** Words is the only thing that drives the caret and pace caret; nothing outside Words calls them; the line-jump/tape-scroll handoff is internal to Words. Decided in T3, a mix: Words renders the caret elements with their style class, visibility (caret: words input focused, test not ending or finished, window not resizing; pace caret: has a target) and blinking (off in focus mode) reactively; movement (position, line-jump and tape-scroll margins) stays anime.js animations on a private imperative handle the words layout owns, so it looks as before. The pace caret's timing is a DOM-free module whose output is a target signal (word, letter, step end). Tribe carets follow the pace caret: Words renders one per player from the room store, each heading for a target (`stepEnd` = now + the room's update rate), and the layout's caret list (`allCarets`) carries their line-jump and tape-scroll handoff; nothing outside Words moves them.
- **TestPage runs all fades**, driven by the engine's phase: words fade out on finish; when the fade-out completes, the result fades in if the result signal has a value, otherwise a spinner fades in and is swapped for the result when it arrives. Restart fades follow the restart flow above.
Expand Down
5 changes: 4 additions & 1 deletion frontend/__tests__/__harness__/test-page.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,6 @@ import { vi } from "vitest";
import type { WordStatus } from "../../src/ts/components/pages/test/Word";
import type { LetterStatus } from "../../src/ts/components/pages/test/WordLetter";

import { LETTER_SELECTOR } from "../../src/ts/components/pages/test/selectors";
import { TestPage } from "../../src/ts/components/pages/test/TestPage";
import { __testing as configTesting } from "../../src/ts/config/testing";
import { compose, deleteWord, typeText } from "../../src/ts/dev/typing-driver";
Expand All @@ -78,6 +77,10 @@ import {
import * as CustomText from "../../src/ts/test/custom-text";
import { paceCaretTarget } from "../../src/ts/test/pace-caret";

// tests check the rendered DOM itself, not the registry's refs, so they
// query letters directly (spec Q33 exempts tests)
const LETTER_SELECTOR = '[data-ui-element="letter"]';

// fake timers, then jsdom gaps: matchMedia (ad controller, on import; no
// query matches) and scrolling (the test keeps itself in view)
vi.hoisted(() => {
Expand Down
171 changes: 171 additions & 0 deletions frontend/__tests__/components/pages/test/Word.spec.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,171 @@
import "../../../__harness__/mock-static";
import { render } from "@solidjs/testing-library";
import { Show } from "solid-js";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";

import {
Caret,
isCaretDebug,
toggleCaretDebug,
} from "../../../../src/ts/components/pages/test/caret";
import { Word } from "../../../../src/ts/components/pages/test/Word";
import {
createWordRegistry,
type WordRegistry,
} from "../../../../src/ts/components/pages/test/word-registry";
import {
appendRenderedWord,
replaceWords,
resetWordsRender,
setWordInput,
wordsRenderState,
} from "../../../../src/ts/states/words-render";

// tests check the rendered DOM itself, not the registry's refs, so they
// query letters directly (spec Q33 exempts tests)
const LETTER_SELECTOR = '[data-ui-element="letter"]';

let frames: Map<number, FrameRequestCallback>;

function flush(): void {
const pending = [...frames.values()];
frames.clear();
for (const cb of pending) cb(0);
}

/** Renders word 0 on its own, registering it in a fresh registry. */
function renderWord(): { registry: WordRegistry; container: HTMLElement } {
const registry = createWordRegistry();
const { container } = render(() => (
<Show when={wordsRenderState.words[0]}>
{(word) => (
<Word
word={word()}
isActive={() => true}
register={registry.registerWord}
/>
)}
</Show>
));
return { registry, container };
}

/** Word 0's letters as the registry hands them out, undefined if unregistered. */
function registeredLetters(registry: WordRegistry): Element[] | undefined {
const word = registry.getWord(0);
if (word === undefined) return undefined;
return Array.from({ length: word.getLetterCount() }, (_, i) =>
word.getLetter(i),
).filter((l) => l !== undefined);
}

function renderedLetters(container: HTMLElement): Element[] {
return [...container.querySelectorAll(`.word > ${LETTER_SELECTOR}`)];
}

beforeEach(() => {
frames = new Map();
let nextFrameId = 1;
vi.stubGlobal("requestAnimationFrame", (cb: FrameRequestCallback) => {
const id = nextFrameId++;
frames.set(id, cb);
return id;
});
vi.stubGlobal("cancelAnimationFrame", (id: number) => frames.delete(id));
});

afterEach(() => {
if (isCaretDebug()) toggleCaretDebug();
resetWordsRender();
frames.clear();
vi.unstubAllGlobals();
});

describe("Word", () => {
describe("letter refs", () => {
it("registers its rendered letters in order", () => {
appendRenderedWord({ display: "abc" });
flush();
const { registry, container } = renderWord();

expect(registry.getWord(0)?.el).toBe(container.querySelector(".word"));
expect(registeredLetters(registry)).toEqual(renderedLetters(container));
expect(registeredLetters(registry)).toHaveLength(3);
});

it("follows extra letters and backspace", () => {
appendRenderedWord({ display: "ab" });
flush();
const { registry, container } = renderWord();

setWordInput(0, "abcd");
flush();
expect(registeredLetters(registry)).toHaveLength(4);
expect(registeredLetters(registry)).toEqual(renderedLetters(container));

setWordInput(0, "a");
flush();
expect(registeredLetters(registry)).toHaveLength(2);
expect(registeredLetters(registry)).toEqual(renderedLetters(container));
});

it("follows the input in zen", () => {
replaceWords([], { activeWordIndex: 0, zen: true });
appendRenderedWord({ display: "" });
flush();
const { registry, container } = renderWord();

setWordInput(0, "hey");
flush();
expect(registeredLetters(registry)).toHaveLength(3);
expect(registeredLetters(registry)).toEqual(renderedLetters(container));

setWordInput(0, "h");
flush();
expect(registeredLetters(registry)).toEqual(renderedLetters(container));
});

it("unregisters when unmounted", () => {
appendRenderedWord({ display: "abc" });
flush();
const { registry, container } = renderWord();
expect(registeredLetters(registry)).toHaveLength(3);

resetWordsRender();
flush();
expect(container.querySelector(".word")).toBeNull();
expect(registry.getWord(0)).toBeUndefined();
});
});

describe("caret debug", () => {
it("outlines the letters and marks the pace caret's target", () => {
appendRenderedWord({ display: "abc" });
flush();
const { registry, container } = renderWord();
const letters = renderedLetters(container);

toggleCaretDebug();
expect(letters.every((l) => l.classList.contains("debugCaret"))).toBe(
true,
);

const wordsWrapper = document.createElement("div");
const paceCaret = new Caret(document.createElement("div"), {
isMainCaret: false,
style: () => "default",
wordsWrapper: () => wordsWrapper,
wordRegistry: registry,
});
paceCaret.goTo({ wordIndex: 0, letterIndex: 0, testDirection: "ltr" });
expect(letters[0]?.classList.contains("debugCaretTarget")).toBe(true);
expect(letters[1]?.classList.contains("debugCaretTarget")).toBe(false);

toggleCaretDebug();
for (const l of letters) {
expect(l.classList.contains("debugCaret")).toBe(false);
expect(l.classList.contains("debugCaretTarget")).toBe(false);
}
});
});
});
48 changes: 4 additions & 44 deletions frontend/__tests__/components/pages/test/Words.spec.tsx
Original file line number Diff line number Diff line change
@@ -1,12 +1,6 @@
import "../../../__harness__/mock-static";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";

import {
Caret,
isCaretDebug,
toggleCaretDebug,
} from "../../../../src/ts/components/pages/test/caret";
import { LETTER_SELECTOR } from "../../../../src/ts/components/pages/test/selectors";
import { setConfigStore } from "../../../../src/ts/config/store";
import { getDefaultConfig } from "../../../../src/ts/constants/default-config";
import {
Expand All @@ -30,6 +24,10 @@ import {
} from "../../../../src/ts/states/words-render";
import { renderWords } from "../../../__harness__/render-words";

// tests check the rendered DOM itself, not the registry's refs, so they
// query letters directly (spec Q33 exempts tests)
const LETTER_SELECTOR = '[data-ui-element="letter"]';

let frames: Map<number, FrameRequestCallback>;
let nextFrameId: number;

Expand Down Expand Up @@ -89,7 +87,6 @@ afterEach(() => {
setTestFocusState("focused");
setJoiningScript(false);
setIsLanguageRightToLeft(false);
if (isCaretDebug()) toggleCaretDebug();
resetWordsRender();
frames.clear();
vi.unstubAllGlobals();
Expand Down Expand Up @@ -783,41 +780,4 @@ describe("Words", () => {
expect(wordsRenderState.keepsLineBreaks).toBe(false);
});
});

describe("caret debug", () => {
it("outlines the letters and marks the pace caret's target", () => {
const container = renderWords();
appendRenderedWord({ display: "abc" });
flush();
const letters = [
...(wordEls(container)[0]?.querySelectorAll(LETTER_SELECTOR) ?? []),
];

toggleCaretDebug();
expect(letters.every((l) => l.classList.contains("debugCaret"))).toBe(
true,
);

const wordsWrapper = document.createElement("div");
const paceCaret = new Caret(document.createElement("div"), {
isMainCaret: false,
style: () => "default",
wordsWrapper: () => wordsWrapper,
});
paceCaret.goTo({
wordIndex: 0,
wordEl: wordEls(container)[0],
letterIndex: 0,
testDirection: "ltr",
});
expect(letters[0]?.classList.contains("debugCaretTarget")).toBe(true);
expect(letters[1]?.classList.contains("debugCaretTarget")).toBe(false);

toggleCaretDebug();
for (const l of letters) {
expect(l.classList.contains("debugCaret")).toBe(false);
expect(l.classList.contains("debugCaretTarget")).toBe(false);
}
});
});
});
Loading
Loading