Skip to content

refactor: letter refs through the word registry (T4b) (@miodec) - #8593

Open
Miodec wants to merge 29 commits into
masterfrom
refactor/letter-refs
Open

Miodec wants to merge 29 commits into
masterfrom
refactor/letter-refs

Conversation

@Miodec

@Miodec Miodec commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Stacked on #8567 (T4). Roadmap step T4b, spec Q33.

Summary

Letters reach the caret, words layout and TypoHints through refs, not LETTER_SELECTOR queries.

 <Words>
   createWordRegistry()
   <Word register={registry.registerWord}>
+    letterRefs (private), filled by refs, trimmed on <Index> cleanup
+    registers MountedWord { el, getLetter(i), getLetterCount() }
-    <WordLetter />
+    <WordLetter ref={(el) => (letterRefs[i] = el)} />
-    <TypoHints word />                 # queried :scope > letter
+    <TypoHints word getLetter={getLetter} />
 words layout
-  new Caret(el, { … })
+  new Caret(el, { …, wordRegistry: registry })
-  caret.goTo({ wordIndex, wordEl, letterIndex })   → wordEl.qsa(LETTER_SELECTOR)
+  caret.goTo({ wordIndex, letterIndex })           → registry.getWord(i).getLetter(j)
-  getTapeLetterShift(activeWordEl.qsa(LETTER_SELECTOR))
+  getTapeLetterShift(registry.getWord(i))
-  getNlCharWidth / overflow probe → qsa(LETTER_SELECTOR)
+  getNlCharWidth / overflow probe → registry.getWord(i).getLetter(j)
  • selectors.ts deleted; dev/expose.ts and tests keep a local selector.
  • Word's letter array stays private: readers go through the handle, read at use.
  • Letter helpers take HTMLElement instead of ElementWithUtils (no wrapping per letter).
  • Caret debug's reactive marking already landed on master (280cc0c); this keeps it.

Evidence

  • New Word.spec.tsx: the registered handle's letters match the rendered ones in order through extras, backspace and zen; unregistered on unmount; caret debug classes on/target/off (pace caret built with the registry). Full suite: 115 files, 1870 tests pass.
  • Browser (__mt.checkLayout() empty, caretOffset within 2–4px): normal, tape letter, tape word; mixed Hebrew/Arabic/English custom text in all three; newlines in tape modes; line jump with long words and extras (overflow probe caps extras before the 20-extra limit at font size 4); typo hints centred under their letters; caret debug outlines + red target, cleared on toggle off.

Merge Danger

Door: two-way

Blast Radius: typing test

Caret position, tape scroll, line jumps, overflow guard and typo hints all read letters from the new refs; a stale ref would misplace the caret or hints.

🤖 Generated with Claude Code

Miodec and others added 22 commits November 9, 2026 23:58
With the dots typed effect, joining script letters stay inline, so they
stay joined, keep the word's width and wrap with it; each typed letter draws
its dot over itself. A copy of the letter (::before, from data-char) runs the
same shrink as non-joining letters. No measuring: the break-joining module,
its layout calls and config effects are deleted, and nothing writes into
Word elements from outside any more (classList -> cn).

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>
Words renders #caret and #paceCaret (data-ui-element caret/paceCaret)
with reactive style class, visibility and blinking; movement stays on a
private Caret handle owned by the words layout. Pace caret timing is
DOM-free and outputs a target signal. The caret and tape read the typed
input from the render store. Fixes the tape caret offset in words whose
direction differs from the test's.

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>
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>
- dev handle finds the caret by data-ui-element, not #caret
- new words move the pace caret to the start whenever it's mounted (hidden
  until it has a target), so the layout drops pace-caret's on/off rule
- test-page harness mocks canvas-confetti; caret hides as soon as a timed
  test runs out
- roadmap: L3 takes the caret position from a handle signal, L12 moves the
  themes and crt.css off the caret ids

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
# Conflicts:
#	docs/specs/solid-monkeytype/roadmap.md
#	docs/specs/solid-monkeytype/spec.md
#	frontend/__tests__/test/test-ui-words.spec.tsx
#	frontend/src/ts/components/pages/test/words-layout.ts
…late (@Miodec)

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

caret.scss, the bundled themes and the crt funbox select the carets by
data-ui-element and their style by data-ui-variant. The #caret id and the
style classes stay for legacy themes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Words creates its own registry; Word and line breaks register through a
prop, the layout hands the caret the word element. Only the overflow check
is exported. LETTER_SELECTOR moves to the test page's selectors module.

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>
…admap

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
# Conflicts:
#	docs/specs/solid-monkeytype/roadmap.md
#	docs/specs/solid-monkeytype/spec.md
#	frontend/src/ts/components/pages/test/Words.tsx
#	frontend/src/ts/components/pages/test/caret.ts
#	frontend/src/ts/components/pages/test/words-layout.ts
Each Word keeps its letter elements (WordLetter callback refs) and
registers them with its element; caret, words layout and TypoHints use
them instead of LETTER_SELECTOR queries. Caret debug marking is reactive
on WordLetter. selectors.ts deleted; dev and tests keep a local selector.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@monkeytypegeorge monkeytypegeorge added frontend User interface or web stuff docs Related to Markdown files and documentation labels Nov 17, 2026
…try-private

# Conflicts:
#	frontend/__tests__/components/pages/test/Words.spec.tsx
# Conflicts:
#	frontend/__tests__/components/pages/test/Words.spec.tsx
#	frontend/src/ts/components/pages/test/WordLetter.tsx
#	frontend/src/ts/components/pages/test/caret.ts
Base automatically changed from refactor/word-registry-private to master November 17, 2026 18:23
The registry stores a WordElements handle per word (el, letter(i),
letterCount()) instead of exposing Word's live letters array. Carets
are built with the registry, so goTo takes indexes only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings November 17, 2026 19:31
@github-actions github-actions Bot added the waiting for review Pull requests that require a review before continuing label Nov 17, 2026
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

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

A critical active issue remains in frontend/src/ts/components/pages/test/Word.tsx where Solid’s index accessor is treated like a numeric index, risking broken letterRefs registration and incorrect caret/layout measurement.

1 open issue
What changed in this PR

Refactors typing-test letter access so caret, layout, and TypoHints read rendered letters via per- registry refs (T4b / spec Q33), removing app-code selector-based letter queries.

Changes:

  • Introduce a Words-owned word registry and register per-word handles for letter access.
  • Wire per-letter callback refs from WordLetter → Word and expose letter lookup to caret/layout/TypoHints.
  • Remove legacy shared selector/word-elements plumbing from app code; keep local selectors only in dev/tools/tests and add/update coverage + docs.
File Description
frontend/​src/​ts/​states/​word-elements.ts Removes the legacy global word/line-break elements registry and shared selector-based helpers.
frontend/​src/​ts/​dev/​expose.ts Updates dev tooling to use a locally-defined letter selector after app-code selector removal.
frontend/​src/​ts/​components/​pages/​test/​Words.tsx Creates a per-Words registry instance and passes registration callbacks down to Word/LineBreak for lookup by layout/caret.
frontend/​src/​ts/​components/​pages/​test/​words-layout.ts Refactors tape/newline/overflow measurement logic to read letters through the registry instead of querying the DOM.
frontend/​src/​ts/​components/​pages/​test/​WordLetter.tsx Adds a callback ref so each rendered element can be captured by its parent Word.
frontend/​src/​ts/​components/​pages/​test/​Word.tsx Collects per-letter refs, registers a WordElements handle into the registry, and passes letter access down to TypoHints.
frontend/​src/​ts/​components/​pages/​test/​word-registry.ts Introduces a Words-owned registry for registering and retrieving word/line-break handles and their letter accessors.
frontend/​src/​ts/​components/​pages/​test/​TypoHints.tsx Switches hint positioning/measurement from scoped selector queries to a provided letter accessor function.
frontend/​src/​ts/​components/​pages/​test/​caret.ts Updates caret positioning and tape interactions to resolve word/letter elements via the registry rather than selector queries.
frontend/​__tests__/​test/​words-wrapper-height.spec.ts Adjusts wrapper height/layout tests to work with the new registry-based wiring instead of the removed global registry.
frontend/​__tests__/​components/​pages/​test/​Words.spec.tsx Updates Words tests to align with the new registry approach while keeping DOM assertions via local selectors where needed.
frontend/​__tests__/​components/​pages/​test/​Word.spec.tsx Adds coverage ensuring registered letters track rendered output across updates/unmount and that caret-debug marking still behaves correctly.
frontend/​__tests__/​components/​pages/​test/​word-registry.spec.ts Adds unit tests for registry register/unregister behavior and separation of word vs line-break entries.
frontend/​__tests__/​__harness__/​test-page.tsx Keeps a local letter selector for harness-level DOM assertions after app-code selector removal.
docs/​specs/​solid-monkeytype/​spec.md Updates the spec documentation to describe ref/registry-based letter access and the selector-query ban in app code (Q33).
docs/​specs/​solid-monkeytype/​roadmap.md Updates roadmap entries to reflect completion of T4/T4b and document the ref-based approach.

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

Comment on lines +76 to +84
{(letter, i) => {
// removed letters are always the last ones
onCleanup(() => {
letterRefs.length = Math.min(letterRefs.length, i);
});
return (
<WordLetter letter={letter()} ref={(el) => (letterRefs[i] = el)} />
);
}}
Miodec and others added 3 commits November 17, 2026 20:40
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>
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 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