Number Sense

There’s always another way.

Number Sense is a focused daily math game about seeing the structure of a calculation and changing it into a friendlier form. The numbers and expressions are the game: there is no arcade, surfing, or movement layer.

V2 supports:

• addition through compensation and place-value splits;
• subtraction through compensation and visible sign changes;
• multiplication through the established distributive and regrouping paths;
• division through integer-friendly divisible chunks;
• Mixed mode, unlocked after completing each individual operation once.

A first visit opens a short interactive 49 + 26 lesson on the real math surface. It asks the player to turn 49 into 50 − 1, then briefly connects the same idea to subtraction, multiplication, and division. Completion or Skip for now is stored separately from daily progress, and ? can replay the lesson at any time.

Run Number Sense

Requirements: Node.js 22 (.node-version pins the locally verified 22.21.0) and npm.

npm ci
npm run dev

The experience supports keyboard, mouse, touch, reduced motion, and narrow viewports.

Quality commands

npm run typecheck
npm run lint
npm test
npm run build

npm run preview serves the production build after npm run build.

The daily loop

1. Choose Addition, Subtraction, Multiplication, or Division.
2. Solve a problem directly, or select either operand and rewrite it with +, −, ×, or ÷.
3. Watch the equivalent form propagate through the calculation.
4. Keep manipulating visible numbers, enter a bounded equivalent answer expression, or request local help.
5. See a contrasting authored strategy. Try it interactively or move to the next problem.
6. Complete one warm, one exploratory, and one puzzle-like problem.
7. Unlock Mixed after completing all four operation modes.

The problem generators select only strategy-friendly structures. Division problems have integer quotients and authored chunks divisible by the divisor. Mixed mode deliberately combines three different operations each day; it is not arbitrary operator randomization.

Progress, discoveries, hints, operation completion, and the daily result are stored locally in versioned records. Legacy multiplication snapshots and historical removed-surf phases still migrate safely.

Player input and teaching suggestions intentionally use different standards. Any safe equivalent decomposition remains valid player mathematics; the presence can select only authored, rationale-tagged TeachingView metadata.

Project map

src/
  app/                 composition, tutorial isolation, local progress
  components/          shell, mode entry, help, and results
  data/                strategy-friendly generators and deterministic selection
  features/math/       central mathematical interaction
  features/spirit/     authored alternative reveal and replay choice
  features/tutorial/   first-run interactive lesson
  game/                reducer, persistence, operation unlocks, and sharing
  math/                safe AST, evaluation, rewriting, hints, and strategy detection
  styles/              global tokens and baseline styles
docs/                   architecture, math, design, decisions, and development record

Deployment

Number Sense is a single-route static Vite site. Vercel and Render install with npm ci, build with npm run build, and publish dist. It has no backend or required environment variables. The repository is configured for Vercel and a Render Static Site. Both install with npm ci, build with npm run build, and publish dist; neither runs a backend.

Product boundaries

V2 intentionally excludes algebra variables, fraction-focused play, advanced decimals, percentages, exponents, graphing, accounts, social systems, AI tutoring, monetization, large meta-progression, and unrelated gameplay systems.