# Changes & Rationale

This document explains how the codebase was improved and why. Each item notes
the original behavior, the change, and the reasoning.

## 1. Three-tier design-token architecture

**Before:** Tokens were split across `streem_theme/colors.rs`,
`streem_theme/shapes.rs`, `streem_theme/typography.rs` (writing into
`mod.widgets.*`), while the actual themes lived in `streem_theme/mod.rs`
(`mod.streem_theme.*`). The token files were also **not declared as Rust
modules anywhere**, so they were effectively dead code that never ran.

**After:** A clean 3-tier system:
1. `streem_design/{palette,shapes,typography}.rs` — tier-1 primitives.
2. `streem_theme/mod.rs` — tier-2 semantic themes that bind roles to primitives.
3. Widgets — read only the active theme (`s_themes`) / language (`s_i18n`).

**Why:** This is the standard, scalable token model. Changing one palette
entry re-brands everything; widgets never reference raw values.

> **Registration note:** the tier-1 modules use `script_eval!` (runtime
> mutation of the `mod` object), *not* the `script_mod!` macro form. The
> `script_mod!` form returns a value to be applied to a component and does not
> eagerly install a fresh top-level namespace like `mod.streem_design.*`, which
> is exactly why the original `colors.rs`/`shapes.rs`/`typography.rs` (written
> with `script_mod!` but never wired up) produced "`streem_design` not found"
> errors. `script_eval!` installs the namespace immediately, matching the
> working `streem_theme` / `streem_i18n` pattern. Inside `script_eval!` there is
> no prelude `use`, so fonts are referenced by their fully-qualified path
> (`mod.theme.font_bold`) rather than the bare `theme.font_bold` alias.

## 2. App-owned namespace (`mod.streem_design.*`)

**Before:** Tokens were written into `mod.widgets.*`.

**After:** All app tokens live under `mod.streem_design.*`.

**Why:** `mod.widgets.*` is the framework's widget namespace; writing app
tokens there is confusing and risks collisions. An app-owned namespace makes
ownership explicit.

## 3. Themes reference palette primitives (single source of truth)

**Before:** `streem_theme/mod.rs` inlined hex literals (`color_bg: #FFF7ED`,
`color_primary: #D97706`, …), duplicating values and divorcing themes from any
shared palette.

**After:** Each theme role points at a palette token
(`color_primary: mod.streem_design.palette.amber_600`).

**Why:** One palette edit now propagates to every theme that uses it; the
palette becomes the single source of truth.

## 4. Fixed the unused `color_text` role

**Before:** Both themes defined `color_text`, but the UI never used it — body
text relied on widget defaults (white), which is invisible on light surfaces.

**After:** Semantic roles (`color_text`, `color_text_secondary`,
`color_text_on_primary`) are explicitly applied to the title, subtitle,
status, and section labels.

**Why:** Per the Splash manual, default text color is white; light themes must
set dark text explicitly or it disappears (white-on-white).

## 5. Live, data-driven status label

**Before:** The DSL hard-coded `text: "Current: light  |  reapply: 0"`, a
string that could drift out of sync with actual state.

**After:** The label starts neutral and is always written from Rust state via
`refresh_status` (`Current: {theme} / {lang}  |  reapply: {n}`), called on
startup, on every toggle, and on live-edit.

**Why:** A single source of truth prevents the displayed status from lying.

## 6. Generic theme cycling (no rigid 2-state enum)

**Before:** A `ThemeState { Light, Dark }` enum with `toggled()` hard-coded the
two-theme assumption.

**After:** The host tracks `theme_idx` / `lang_idx` into ordered name lists
(`THEMES`, `LANGS`) that mirror `theme_names` / `lang_names` in script. Toggling
advances the index modulo the list length.

**Why:** Adding a third theme (or third language) now requires no host changes
to the cycling logic — just extend the lists.

## 7. Runtime language switching

**Before:** i18n existed but was never wired to the UI, and it defaulted to
Swahili (`s_i18n = sw`), which looked like a leftover.

**After:** A **Language** button cycles `en`/`sw`; the active language is
selected alongside the theme in the single `reapply` reload path. Default is
now English.

**Why:** Demonstrates that the same swap-and-reload mechanism localizes the UI,
not just re-colors it.

## 8. Single reload path

**Before:** `apply_theme` and `reload_ui_from_rust_state` overlapped and both
re-applied the theme; the flow was easy to get out of sync.

**After:** One `reapply(cx)` selects the active theme+language in the VM,
reloads the script tree, refreshes the status label, and redraws. `handle_*`
methods call it once when something changes.

**Why:** Less duplication, clearer control flow, no double application.

## 9. Hardened `Event::LiveEdit`

**Before:** On `LiveEdit`, the app called `apply_theme` (which re-evaluated the
theme but could leave i18n/state inconsistent after a hot reload).

**After:** On `LiveEdit`, the app re-selects the active theme *and* language in
the VM and refreshes the status, so a hot reload preserves the user's current
selection instead of reverting to script defaults.

**Why:** Hot-reloading code shouldn't silently reset the user's theme/language.

## 10. Expanded, polished UI consuming the tokens

**Before:** A minimal toggle + two markup cards with magic-number padding and
inline `font_size` values.

**After:** A header (title/subtitle), a control bar (themed buttons + live
status), and two bordered surface cards — all driven by the spacing scale,
typography styles, semantic colors, and `new_batch: true` on text-bearing
backgrounds (per the Splash batching guidance, so text never hides behind its
own background).

**Why:** Shows the design system actually being consumed end-to-end and
follows the documented layout/batching best practices.

## 11. Better tests

**Before:** One test that checked the enum toggles back and forth.

**After:** Tests cover full theme/language cycling and verify the modulo
guards never index out of range.

## 12. Build ergonomics

* `Cargo.toml` documents the expected sibling-of-Makepad layout for the path
  dependency and provides a commented, branch-pinned git fallback.
* Added a `markup` feature (default on) for the Markdown/Html widgets.
* Added `.gitignore` for `target/`.