The theoretical foundation of the project is compiled in the main concept ["uchitsya-legko.rf — learning to read as decoding a written code"](/concepts/uchitsya-legko-rf-obuchenie-chteniyu-kak-deshifrovke-pismennogo-koda). It is the central point of the project: it describes the general model, current state, and connects specific concepts.

The project is currently at the **Idea** stage. The basic theory of reading as information reconstruction from a written code has been formed. The information entities on which learning is built have been recorded: object and situation, concept, image, spoken word, sound, written word, letters, and larger structural parts of a word.

Key components of the theory:

- [Reading is word recognition and meaning reconstruction, not sequential letter sounding](/concepts/chtenie-eto-raspoznavanie-slova-i-vosstanovlenie-smysla).
- [A written word connects several representations of the same content](/concepts/pismennoe-slovo-svyazyvaet-neskolko-predstavleniy).
- [Learning to read should go from known supports to the unknown code](/concepts/obuchenie-chteniyu-ot-izvestnyh-opor-k-neizvestnomu-kodu).
- [The oral vocabulary is the recognition base when learning to read](/concepts/ustnyy-slovar-baza-raspoznavaniya-pri-obuchenii-chteniyu).
- [A long word must be revealed through familiar structural parts](/concepts/dlinnoe-slovo-cherez-znakomye-strukturnye-chasti).
- [Hints must gradually disappear as connections are mastered](/concepts/podskazki-dolzhny-postepenno-ischezat).

The practical direction is an interactive system where the child starts with recognizable objects and words, confirms their sound, gets acquainted with the spelling, discovers repeating elements of the written code, and then applies the discovered correspondences to decode new words.

Critical principle: the system must not simultaneously require the mastery of several unknown levels. If the child does not know the concept, the spoken word, its sound, and the letters, such a word is poorly suited as starting material. The next task must rely on the already confirmed knowledge of the specific child.

The next stage of the project is to turn the theory into minimal interactive mechanics and test the main criterion: is the child able to transfer mastered correspondences to previously unseen words, rather than just memorizing shown examples.

An interactive project for teaching reading as the gradual decoding of a written code through meanings, images, and spoken words already familiar to the child.

uchitsya-legko.rf

## Task

Extract the common execution logic of `VoiceScenario` into a single runtime module and use it simultaneously in both the synthesizer and the visualizer.

Currently, the logic for `prepareScenario`, `evaluateBezier`, `updateAutomations`, `executeCommand`, and the computation of the current `VoiceControlState` is essentially duplicated. This creates a risk of divergence: the visualizer might display a state different from the one actually used by the DSP.

## What needs to be done

- Create a shared runtime module for `VoiceScenario` (e.g., `VoiceSynthesizer/src/runtime.ts`).
- Extract the preparation of scenario composition and the general timeline there.
- Extract the interpretation of `set` and `animate`.
- Extract cubic bezier calculation.
- Extract the updating of active automations and the semantics of preserving `to` values after `duration` ends.
- Ensure the ability to obtain the actual `VoiceControlState` over time or iterate the state along the timeline.
- Migrate `synthesizeScenario` to this runtime.
- Migrate `ScenarioVisualizer` to the same runtime so that the chart reflects the actual state of the synthesizer rather than a separate interpretation of the scenario.
- Preserve the existing semantics of scenario array composition: `initial` is present only on the first scenario, while subsequent ones continue the current state without a reset.

## Acceptance Criteria

For the exact same `VoiceScenario`, the synthesizer and the visualizer use the exact same state machine implementation. After changing the runtime semantics, situations where the DSP executes a scenario one way and the visualizer displays it another way become impossible.

Eliminate duplication of VoiceScenario execution logic between synthesizeScenario and ScenarioVisualizer.

Extract VoiceScenario runtime into a shared module for synthesizer and visualizer

## Context

It is necessary to strictly separate **the core practical interaction with the product** and **the explanatory/marketing layer**.

The user, especially a child, should be able to visit the website and immediately use the mechanics without reading the mission, theory, methodology description, marketing texts, or principle explanations.

At the same time, all project theory, argumentation, research, principles, explanations of the approach, and SEO content must be available separately for parents, teachers, adult learners, and other interested users.

For this, a blog is needed.

## Key Technical Principle

**The blog must not be a separate technical entity.**

It must be built on top of already existing concepts.

The main differentiation mechanism is the `type` field on the concept.

It is necessary to design and implement a **concept types directory** in advance, where blog types will have a single namespace:

```text
blog:default
blog:article
```

and other types starting with:

```text
blog:
```

In other words, a blog is not a separate data model, but a way of classifying, querying, and rendering concepts.

## What Needs to Be Designed

- define the general `type` system for concepts;
- define the `blog:*` namespace;
- decide which specific blog types are needed;
- fix the purpose of each type;
- determine which type is the base/default one;
- determine which concept fields are used for blog rendering;
- define URL/routing rules;
- define publication list rules;
- define individual article display rules;
- determine how blog concepts are linked to regular knowledge concepts;
- determine whether the same materials can simultaneously participate in the knowledge structure and the blog;
- define filtering by `type`;
- implement the types directory in a way that avoids scattering string values throughout the code;
- provide for future type expansion without altering the data model;
- define SEO fields and rules for blog materials;
- define how the indexable blog structure is formed;
- define thematic navigation without turning the blog into the main entry point to the product.

## Potential Types

Starting examples:

```text
blog:default
blog:article
```

Additional types need to be defined separately within the task scope. Possible directions to evaluate:

- overview;
- research;
- methodological material;
- note;
- case study;
- principle explanation;
- SEO article.

At the same time, the specific list must not be fixed solely based on familiar CMS categories — it must reflect the actual ways content is used in the project.

## Architectural Principle

The practical product and the blog must exist independently of each other at the user entry level.

The core logic:

> **the product answers the question "what can I do right now?"**
>
> **the blog answers the question "why is it built this way?"**

A user can use the site for a long time without ever visiting the blog.

The blog is needed for:

- stating the mission and principles;
- explaining methodologies;
- publishing research and findings;
- providing argumentation for parents and teachers;
- SEO;
- accumulating public knowledge around the project;
- building trust;
- explaining product decisions to those who are genuinely interested.

## Constraint

Do not build the blog as the central marketing funnel in front of the product.

Do not introduce a new entity solely for the sake of the blog if the existing concept model already covers this requirement.

First, design the **types directory and presentation rules**, and only then the blog interface.

Implement the blog as a separate presentation of existing concepts via the type system, without introducing a new technical entity.

Implement the blog

# Task

Implement a universal mechanism for all site entities on "Uchitsya legko" that allows a child to independently receive two different types of information:

- **🔊 Speaker** — find out how the entity sounds / is pronounced;
- **? Question** — find out what it is / what it means.

These actions must be separated because **knowing how a word sounds and understanding its meaning are not the same thing**.

## Why This is Needed

The current mechanics work well when the child already knows the object in the picture and knows what it is called. Then the site connects the already known meaning and sound with the new written form: the word, syllables, and letters.

However, it cannot be assumed in advance that the child knows every entity on the site. In the same set, some pictures may be familiar and some may not. Different states of knowledge are also possible:

- the child knows the object and its name;
- knows the object, but does not know what it is called;
- has heard the word, but does not know its meaning;
- knows neither the object nor its name.

Therefore, the interface should not try to pre-determine the child's level. Instead, it should give them simple, universal tools that they will quickly learn to use on their own.

## Basic Mechanics

### "Speaker" Button

On a regular card, the `🔊` button plays the audio for the current entity or its name.

Example:

- the child sees a picture of a tapir;
- clicks on the word `TAPIR` or the `🔊` button;
- hears: "tapir".

This makes it possible to establish a connection between the image, sound, and written form even if the name was previously unknown.

### "?" Button

The `?` button opens the expanded state of **the same card**.

It retains:

- the picture;
- the word;
- other existing card elements;

and additionally displays a **short text description of the entity**.

Example:

> A tapir is a large animal with a short trunk. It lives in forests and swims well.

The description itself **should not play automatically** when opened.

There should be a separate `🔊` button next to the description. The `?` button is no longer present in this state, since the child has already opened the entity explanation.

## Description Voiceover

When clicking `🔊` next to the description, the entire text is read aloud.

During playback, there should be a **synchronous background visual transition / text highlighting as the sound progresses**.

The purpose of this effect is to show the child the direct correspondence between spoken speech and written text.

Even if the child does not yet know what a sentence, word, or writing as a system is, they begin to observe a pattern:

**sound does not appear by itself — it corresponds to what is written on the screen.**

## Clickable Words Within the Description

Each individual word in the text description must be clickable.

When clicked, the word is pronounced separately.

Example:

Text:

> A tapir lives in the forest.

During full playback, the highlight consistently moves across the words:

`Tapir → lives → in → the → forest`

After that, the child can separately click:

- `lives` → hear "lives";
- `forest` → hear "forest".

In this way, the child can independently notice that:

- all text has a sound;
- the sound is connected to what is written;
- the written form is divided into separate parts;
- each part corresponds to its own sound;
- individual words combine into a common sounding phrase.

This creates a natural transition from the current mechanics of `word → syllables → letters` to a higher level of `text / sentence → words`, without the need to pre-explain the theory of sentences or writing to the child.

## General Interface Principle

The mechanics should be universal for the site's entities:

- `🔊` — **how does this sound / how is it pronounced?**
- `?` — **what is this / what does this mean?**

The child should quickly master the purpose of these two elements and independently choose which level of information they need in a particular case.

It is important not to mix these functions: opening an explanation should not automatically trigger long audio, and knowing the pronunciation should not be considered equivalent to understanding the meaning.

## Connection to the Main Task

This task is a subtask of [Task "Develop the second level of literacy acquisition: reading sentences and punctuation"](/tasks/cmu4sta4y0ldaqw0qjcf497ne).

The mechanics are important as an independent extension of the current level and as a basis for further mastering more complex writing structures.

Add universal "Speaker" and "?" buttons for independent learning of entity meanings and pronunciations, including voiceover of text explanations with synchronous highlighting.

Tasks

Implement universal "What is it?" mechanics and entity voiceover

Implement the blog

Extract VoiceScenario runtime into a shared module for synthesizer and visualizer