feat(story): add story typing mode with flash, short, and epic length tiers (@albindavidc)

[albindavidc]

Description

Hi MonkeyType team! 👋

I'm a long-time user of MonkeyType and I've always loved how the different modes each bring a distinct feel to the typing experience. I wanted to contribute something that adds a new dimension to that — so I built story mode.

In addition to our existing words, quotes. Story mode lets users type short/medium/long stories — narratives with flow, punctuation, and meaning. It feels different from any existing mode: you're reading something as you type it. It rewards focus.

Users can choose a length tier:

• flash — a single paragraph, roughly 50 words, great for a quick session
• short — 3 paragraphs, a satisfying short read
• epic — 7 paragraphs, a proper challenge

A random story is selected each session within the chosen tier, avoiding immediate repeats. The initial content ships with English stories across all three tiers, following the same static JSON pattern used by quotes and languages — so adding more languages is straightforward.

---

Files changed:

• packages/schemas/src/shared.ts — added story to PersonalBestsSchema
• packages/schemas/src/configs.ts — added StoryLengthSchema and storyLength to ConfigSchema
• packages/schemas/src/stories.ts — new: StorySchema, StoryFileSchema, StoryLengthSchema
• packages/schemas/src/index.ts — exported stories schema
• packages/contracts/src/stories.ts — new contract for GET /stories/:language
• packages/contracts/src/index.ts — registered stories contract
• packages/contracts/src/util/api.ts — added "stories" to OpenApiTag
• packages/contracts/src/rate-limit/index.ts — added storiesGet rate limit
• frontend/src/ts/constants/default-config.ts — added storyLength: "flash" default
• frontend/src/ts/config.ts — added setStoryLength()
• frontend/src/ts/config-metadata.ts — added storyLength metadata entry
• frontend/src/ts/test/story.ts — new: story engine (fetch, cache, parse, pick, build word list)
• frontend/src/ts/test/test-config.ts — story mode UI, active button state, animation
• frontend/src/ts/test/words-generator.ts — integrated story words into generateWords()
• frontend/src/ts/test/test-logic.ts — areAllTestWordsGenerated() and config change restart
• frontend/src/ts/test/result.ts — story length in updateTestType()
• frontend/src/ts/event-handlers/test.ts — click handlers for mode and length buttons
• frontend/src/html/pages/test.html — story mode button and storyLength selector
• frontend/src/styles/test.scss — styles for .storyLength
• frontend/static/stories/english.json — initial English story content
• backend/src/dal/story.ts — new DAL: disk read, in-memory cache, English fallback
• backend/src/api/controllers/story.ts — new controller
• backend/src/api/routes/stories.ts — new route
• backend/src/api/routes/index.ts — registered stories route

---

I've tried to follow MonkeyType's existing patterns as closely as possible throughout — the schema structure, contract style, config metadata approach, DAL pattern, and UI conventions all mirror what's already in the codebase. I'm happy to make any changes the team feels are needed, whether that's content adjustments, naming, or anything else. Thank you for the time reviewing this — MonkeyType is a genuinely great project and I hope this is a worthwhile addition. 🙏

---

Checks

• Adding quotes? N/A
• Adding a language? N/A
• Adding a theme? N/A
• Adding a layout? N/A
• Adding a font? N/A
• Make sure the PR title follows the Conventional Commits standard.
• Make sure to include your GitHub username prefixed with @ inside parentheses at the end of the PR title.

---

Reference Images

[github-actions]

Continuous integration check(s) failed. Please review the failing check's logs and make the necessary changes.

[github-actions]

Continuous integration check(s) failed. Please review the failing check's logs and make the necessary changes.

[fehmer]

hi @albindavidc , thank you for your contribution.

How does story mode differ from quotes?

[albindavidc]

Hello @fehmer , Thankyou for reviewing my code. The key difference is

In quotes mode, the typing content consists of short, standalone quotes. These are typically brief sentences that convey wisdom or ideas, intended for quick typing tests, with a maximum length of a paragraph.

In story mode, the content is longer and more continuous. Instead of isolated quotes, users type passages from stories that describe a sequence of events, providing a more sustained typing experience and better simulating real-world text such as articles or books.

So the main difference is the structure and purpose of the text:

• Quotes mode: short, independent sentences conveying wisdom or ideas (up to a paragraph).
• Story mode: longer narrative passages describing a sequence of events. (1 - 7+ paragraphs)

[fehmer]

hi @Abdulbasit0123 ,

quotes are not limited to a short length and can have multiple paragraphs. There is already a filter for different quote length, so the user can pick from short to very long quotes. There is already content of books in the quotes.

[albindavidc]

Hello @fehmer, My name is @albindavidc

Yes its true that there are quotes that is longer. It would be great if we have a flow like stories. If we have implemented stories, then we will be able to learn and enjoy stories while typing. Not every quotes are stories. By seperating will really help us to clearly enjoy typing.

[Abdulbasit0123]

Hi
why am I tagged here? 😬

[fehmer]

Hi why am I tagged here? 😬

sorry, picked the wrong entry from the autocomplete :D

[fehmer]

Hello @fehmer, My name is @albindavidc

Yes its true that there are quotes that is longer. It would be great if we have a flow like stories. If we have implemented stories, then we will be able to learn and enjoy stories while typing. Not every quotes are stories. By seperating will really help us to clearly enjoy typing.

Hi @albindavidc, i feel the use case is very limited compared to the required changes. If we would add like tags to existing quotes we could let the user filter for like fiction, poetry, religious, political. music etc.

[albindavidc]

Hello @fehmer, My name is @albindavidc

Perhaps we could also consider introducing tags to help categorize and filter the content more easily.

For example, in quotes, tags such as wisdom, inspirational, humorous, and leadership could be used to reflect the tone or theme.

Similarly, for stories, we might include tags like fiction, poetry, religious, political, music, and others depending on the type of narrative.

This might make it easier for users to discover and filter content based on their interests.

[albindavidc]

Hello @fehmer, My name is @albindavidc

If it would be helpful, I’d be happy to assist with classifying the 7,700+ quotes and adding appropriate tags.