antialias
/
soroban-abacus-flashcards
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Soroban abacus flashcards and learning tools
2,962 Commits 12 Branches 401 Tags 1.2 GiB
HTML 42.3%
TypeScript 33.9%
JavaScript 21.6%
Python 1.7%
HCL 0.2%
Other 0.1%
Go to file
semantic-release-bot fd7e317151 chore(abacus-react): release v2.15.0 [skip ci] 
# [2.15.0](https://github.com/antialias/soroban-abacus-flashcards/compare/abacus-react-v2.14.0...abacus-react-v2.15.0) (2025-12-08)

### Bug Fixes

* **404:** reset easter egg config on page reload/close ([d6f1c13](d6f1c13317))
* account for SVG preserveAspectRatio in coordinate transforms ([e4e0925](e4e09256c2))
* add 'auto' to RuleMode type to prevent undefined display values ([a8636ca](a8636ca6a2))
* add comprehensive dark mode support to Smart Difficulty controls ([a65feb7](a65feb7344))
* add cooldown after quick-escape to prevent precision mode re-activation ([e885ae7](e885ae7ef4))
* add currentStepEstimate to required fields in JSON schema ([0d66c54](0d66c54991))
* add custom cursor when pointer lock is active ([5d6d6b4](5d6d6b4ddc))
* add missing openDeploymentInfo prop to MinimalNav ([30879d8](30879d8959))
* add missing scaleX and scaleY number conversions ([ae6cc5e](ae6cc5e326))
* add missing selectedContinent to default config and fix ts-expect-error directives ([07e9224](07e92240e8))
* add mode descriptions and remove double borders ([6f2f6d4](6f2f6d444c))
* add quotes around unquoted keys when parsing customCrops.ts ([0add49c](0add49c599))
* add seed and prngAlgorithm fields to all Zod schema versions (V1-V4) ([1782f42](1782f427f1))
* add shuffling to progressive difficulty mode & UI improvements ([38e9982](38e9982c3d))
* add zoom to selected continent and improve click detection ([6651979](6651979ea0))
* align share persistence with user session logic ([72c72fc](72c72fc218))
* calculate total problems correctly in preview API ([25dfb71](25dfb71b3e))
* cancel previous give-up animation when new give-up starts ([c01cb7f](c01cb7f384))
* cap zoom when releasing pointer lock (escape key) ([2331f10](2331f1038c))
* center crosshairs and re-enable pointer lock after escape ([814bf94](814bf949f2))
* change zoom capping to create pause effect instead of slow easing ([f2ca9d1](f2ca9d1ebe))
* combine fast easing with smooth precision mode transition ([cab1fbf](cab1fbff95))
* configure Next.js to transpile [@svg-maps](https://github.com/svg-maps) ES modules ([ebf2b66](ebf2b66910))
* consolidate worksheet validation constants and increase MAX_PAGES to 100 ([0f3ec36](0f3ec369bf))
* correct GPT-5 API parameters and surface actual grading errors ([2d33f35](2d33f35c4d))
* **create:** use inline styles for dynamic gradient backgrounds ([ed25b32](ed25b323e8))
* DevCropTool key quoting and magnifier label positioning ([2e4f22a](2e4f22a522))
* don't show labels for excluded/filtered regions ([a83fbb1](a83fbb1070))
* eagerly load map caches in browser and use Suspense pattern ([db6be73](db6be73a1c))
* eliminate cursor dampening lag when changing direction ([fc08b77](fc08b775db))
* enable page virtualization in worksheet creator ([b675f6c](b675f6c96e))
* enable vertical scrolling in layout controls ([a1b31f4](a1b31f454a))
* enable virtualization for worksheet preview by limiting SSR to 3 pages ([f409e3c](f409e3c2ed))
* ensure entire region path is clickable with pointerEvents: all ([eb94191](eb94191b2e))
* export worksheet schema tables from index ([6a16674](6a1667404f))
* hide abacus on /arcade and /arcade-rooms routes ([77033f0](77033f0b22))
* implement manual click detection using precise cursor position ([156f63f](156f63faaf))
* improve dark mode contrast in OrientationPanel dropdown ([f9e2343](f9e2343ffb))
* improve dark mode for orientation and page buttons ([fe9b9f9](fe9b9f9ffa))
* improve draggable button constraints to avoid action button overlap ([00b0fb2](00b0fb297b))
* improve magnifier zoom calculation for multi-piece regions ([cb4114f](cb4114f344))
* improve magnifier zoom smoothness and debug panel ([639e662](639e662d76))
* improve socket server error messages for better debugging ([5d1ea7d](5d1ea7db2d))
* improve text contrast for selected dropdown items in dark mode ([8d03452](8d0345287f))
* improve zoom easing to threshold by deferring capping ([b355a3f](b355a3fc8f))
* increase sampling density for tiny region detection and show all detected regions ([2c9f760](2c9f760ae9))
* increase super zoom multiplier from 2.5x to 5.0x for Gibraltar ([138e6c0](138e6c071b))
* increase z-index of pointer lock prompt overlay ([5388441](5388441ebb))
* **know-your-world:** actually change magnifier element dimensions to 1/3 ([31a06d6](31a06d6fef))
* **know-your-world:** allow space in name confirmation input ([285b128](285b128bb8))
* **know-your-world:** center setup settings panel horizontally ([5f69fab](5f69fab859))
* **know-your-world:** correctly identify local player for cursor sharing ([7aafe8c](7aafe8c92e))
* **know-your-world:** enable hot/cold only for current player in turn mode ([f5ce53e](f5ce53efc0))
* **know-your-world:** fix celebration timer restart and mobile magnifier dismissal bugs ([0558132](055813205a))
* **know-your-world:** fix hot/cold visual feedback delay ([a6352ec](a6352ec624))
* **know-your-world:** fix pointer lock escape for all edges and add smooth release animation ([a7fa858](a7fa858a29))
* **know-your-world:** fix server/client filter mismatch for USA map ([98e74ba](98e74bae3a))
* **know-your-world:** fix TypeScript build errors ([f622bfa](f622bfab54))
* **know-your-world:** guard against undefined state during session init ([ea8965b](ea8965bc95))
* **know-your-world:** improve crosshair UX and fix mobile Select button ([0584863](0584863bdd))
* **know-your-world:** improve mobile layout for setup screen ([81b44a6](81b44a6422))
* **know-your-world:** improve mobile magnifier positioning and sizing ([9a254e2](9a254e2933))
* **know-your-world:** improve mobile magnifier touch controls ([aee5f21](aee5f21ecc))
* **know-your-world:** make game settings visible in right panel ([11d2d56](11d2d5693c))
* **know-your-world:** move Start button to top-right settings panel ([cc51de3](cc51de35e3))
* **know-your-world:** normalize accented letters for keyboard input ([b27856e](b27856e9fc))
* **know-your-world:** prevent hint bubble closing when toggling settings ([a67c11a](a67c11ae04))
* **know-your-world:** raise auto-zoom thresholds for tiny regions ([17c113e](17c113e68b))
* **know-your-world:** reduce magnifier size to 1/3 of pane dimensions ([61a438d](61a438dd31))
* **know-your-world:** remove confidence gate from hot/cold visual emoji ([7f6b9dd](7f6b9dd558))
* **know-your-world:** remove hovered region label from setup screen ([5bb2288](5bb228883d))
* **know-your-world:** Remove redundant preventDefault calls in touch handlers ([021a75f](021a75f583))
* **know-your-world:** remove tips section from setup screen ([c9e9190](c9e9190937))
* **know-your-world:** replace react-spring with CSS animation for crosshair rotation ([af5e7b5](af5e7b59dc))
* **know-your-world:** restore no-music celebration sounds ([f6d1295](f6d1295c6f))
* **know-your-world:** restore Start button character ([7013a7b](7013a7b068))
* **know-your-world:** stabilize mobile magnifier 1:1 touch tracking ([ab30add](ab30adda25))
* **know-your-world:** suppress hot/cold hints during takeover and give-up ([9f6b425](9f6b425daf))
* **know-your-world:** use getBBox() for consistent takeover positioning ([f8acc4a](f8acc4aa6a))
* **know-your-world:** use localPlayerId for cursor updates in all modes ([5e8c37b](5e8c37b68e))
* **know-your-world:** use shared MAX_ZOOM constant for mobile magnifier ([e4c35e9](e4c35e9425))
* **know-your-world:** use spring-for-speed pattern for smooth crosshair rotation ([b7fe2af](b7fe2af369))
* **know-your-world:** use viewport-based maxHeight for right panel ([a4f9db6](a4f9db6d3f))
* lazy-load map data in know-your-world validator ([07c25a2](07c25a2296))
* lower quick-escape threshold to 15px/frame for easier triggering ([97b214d](97b214da12))
* make map-renderer fill parent container for fit-crop-with-fill ([18b1476](18b14766b2))
* make placeholder pages match actual page dimensions ([4003c5c](4003c5ceb7))
* make useArcadeSocket work without ArcadeErrorProvider ([01740af](01740afcb7))
* merge duplicate style attributes on magnifier SVG ([3eda493](3eda493051))
* move pointer lock management to MapRenderer ([0ed4d13](0ed4d13db6))
* page indicator not tracking scroll when showing all pages ([3d157e3](3d157e32ed))
* page indicator stuck on page 1 due to stale closure ([952ebc7](952ebc7756))
* pass correct parameter for borrow boxes in subtraction ([00d892a](00d892a05c))
* position debug panel opposite from magnifier ([aa80a73](aa80a73664))
* position shared worksheet banner below app nav ([fb3412c](fb3412c9a5))
* **practice:** add 80px top padding to account for app nav height ([a50b268](a50b268d35))
* **practice:** allow vertical overflow for help overlays ([1ddf9fc](1ddf9fc94f))
* **practice:** prevent decomposition math from wrapping ([52ea3f1](52ea3f10fa))
* **practice:** remove overflow clipping to allow help overlays ([e9b123a](e9b123a7b3))
* **practice:** remove redundant 'already at target' message ([e9ccfb9](e9ccfb9186))
* **practice:** use explicit padding to prevent shorthand override ([4c00d92](4c00d92ccb))
* preserve saved seed on page reload ([64ce64b](64ce64bd35))
* preserve seed and prngAlgorithm in config migrations ([b18c412](b18c412736))
* preserve user's scaffolding settings when changing skills ([1eb04ce](1eb04ce0c4))
* prevent duplicate API calls in React StrictMode ([0d59676](0d59676b38))
* prevent modal closure when clicking tabs in AllSkillsModal ([4746e1f](4746e1f8fe))
* prevent regrouping problems in no-regrouping skills and enable progressive difficulty toggle ([59712e1](59712e1021))
* prevent skill name wrapping in mini cards with single-line ellipsis ([a463d08](a463d088d7))
* prevent zoom jump on precision mode activation by resetting spring target ([33d9f15](33d9f15897))
* prevent zoom jump when activating precision mode ([9cb3c89](9cb3c898ec))
* properly apply dark mode hover states in dropdown ([34553ce](34553cebf7))
* properly cycle through problem sets when exceeding unique problem space ([55d4920](55d4920167))
* properly zoom to selected continent in game phases ([e900e44](e900e4465b))
* reduce font size for mini skill card titles to prevent wrapping ([833b481](833b481ebb))
* refactor worksheet config persistence to blacklist approach + Storybook stories ([5b6db58](5b6db588a2))
* regenerate lockfile to remove big.js dependencies ([05fc5cf](05fc5cfe49))
* remove all scaffolding from final mastery skills ([d7bec42](d7bec423e0))
* remove background rect from main map SVG ([7d3c5c3](7d3c5c304b))
* remove duplicate containerRect declaration ([1a690e0](1a690e00b0))
* remove magnifierSpring.zoom from effect dependencies ([5eb2eed](5eb2eeda32))
* remove mispositioned background rect from magnifier SVG ([5815cbe](5815cbee15))
* remove pages from visible set when they leave viewport ([9757449](9757449e21))
* remove redundant 'Teens minus singles' subtraction skill ([e156e87](e156e870df))
* remove regex lookbehind for Safari compatibility ([4d77f1f](4d77f1ffd3))
* remove unused velocity tracking and fix TypeScript errors ([0195a6d](0195a6dc6d))
* replace deprecated path() with curve() in borrow arrows ([47d149c](47d149ca17))
* replace ES module imports with JSON data files ([fb735be](fb735be014))
* resolve auto zoom freeze and stuck zoom issues ([0aee60d](0aee60d8d1))
* respect borrow boxes display setting regardless of actual borrowing ([1aef0f2](1aef0f292f))
* respect operator-specific scaffolding in mastery+mixed mode ([a6472a2](a6472a231b))
* respect user's layout options (problemNumbers/cellBorders) in mastery mode ([e708add](e708add9f2))
* responsive page indicator and settings summary improvements ([93ddc28](93ddc28a3a))
* resume zoom animation immediately when precision mode activates ([7ba7e03](7ba7e03661))
* resume zoom animation immediately when precision mode activates ([7c1f2e5](7c1f2e54c9))
* resume zoom animation when target drops below threshold ([e73b59d](e73b59d510))
* scaffolding changes now apply in mastery+mixed mode ([510f052](510f052978))
* **server:** lazy-load game validators to avoid ES module errors ([a88bd58](a88bd5844c))
* show hot/cold button on iPad with mouse attached ([1333818](1333818bae))
* skip pointer lock request on unsupported devices (iPad) ([d6eb997](d6eb997445))
* stabilize mini skill card height and fix preview updates ([4a52943](4a5294353e))
* take all measurements inside animation callback for label sync ([2191e07](2191e0732b))
* track both SVG units and screen pixels for zoom and dampening ([d72f309](d72f309bad))
* transform screen coordinates to SVG space for isPointInFill() ([4c933be](4c933be48a))
* transmit hovered region ID with network cursor to avoid hit-testing discrepancies ([6c3f860](6c3f860efc))
* **tutorial:** expose activeGroupTargetColumn state to context ([69f759a](69f759a178))
* update AbacusQRCode for qrcode.react v4 compatibility ([0f0c3c6](0f0c3c65e8))
* update operator-specific display rules in mastery+mixed mode ([4174b6d](4174b6d2e7))
* upgrade to Node.js 20 to resolve ES module import issues ([192de5c](192de5c6b5))
* use ± symbol for mixed operator icon consistently ([2695b50](2695b50abe))
* use actual SVG path geometry for region detection instead of bounding boxes ([e255ce2](e255ce2c6f))
* use animated spring for magnifier label positioning ([94d1cdf](94d1cdfcb5))
* use ASCII characters for operator icons to support dark mode ([3bd5c00](3bd5c00d21))
* use correct Unicode minus sign (−) for subtraction operator checks ([0dd9e45](0dd9e45952))
* use dynamic ES module imports for [@svg-maps](https://github.com/svg-maps) packages in know-your-world ([ab94fd3](ab94fd350f))
* use LAN IP instead of localhost for QR code camera uploads ([00b400a](00b400ae8a))
* use screen pixels for zoom, abandon SVG path parsing ([912dc38](912dc385b3))
* use subtle gray highlights for dropdown in dark mode ([8d6170a](8d6170a8c7))
* use SVG viewBox units instead of screen pixels for zoom ([0dcaabb](0dcaabb8a5))
* use white text for selected dropdown items in dark mode ([e1a7375](e1a73758d6))
* **worksheets:** add backward compatibility for displayRules in SmartModeControls ([b956e2d](b956e2d605))
* **worksheets:** add borrowNotation and borrowingHints to DisplayRules interfaces ([3b908ac](3b908ac453))
* **worksheets:** add borrowNotation and borrowingHints to validation fallback ([3f700af](3f700af643))
* **worksheets:** add mastery mode to Zod schema validation ([003f1d1](003f1d11cc))
* **worksheets:** correct Typst array membership syntax for ten-frames rendering ([14b3594](14b359462f))
* **worksheets:** enable borrowNotation and borrowingHints in smart difficulty mode ([8020ee8](8020ee835e))
* **worksheets:** prevent infinite loop when problem space is empty ([02463df](02463df8e5))
* **worksheets:** render operators last for proper layering ([cdd0de7](cdd0de797f))
* **worksheets:** sync preview and download problem generation ([822ef78](822ef78e58))
* **worksheets:** ten-frames not rendering in mastery mode ([b36df3a](b36df3a40c))
* **worksheets:** validation function was converting mastery mode to manual ([4ad687d](4ad687df73))

### Features

* **abacus-react:** add defaultValue prop for uncontrolled mode ([3ce12c5](3ce12c59fc))
* add 'auto' option for scaffolding to defer to mastery progression ([a945a62](a945a620c4))
* add adaptive zoom magnifier for Know Your World map ([1e8846c](1e8846cdb1))
* add AI-powered worksheet grading with GPT-5 vision ([6e95732](6e9573288f))
* add auto scaffolding mode with visual feedback and override notices ([b62db5a](b62db5a323))
* add auto-submit on correct answer + Newton poem blog post ([2f7cb03](2f7cb03c3f))
* add comprehensive error handling for arcade games ([e8c5256](e8c52561a2))
* add continent filtering to Know Your World game ([7bb03b8](7bb03b8409))
* add custom error boundaries with navigation ([73cc418](73cc4185c3))
* add database schema for custom skills and skill customizations ([906fa63](906fa63f24))
* add debug bounding boxes to magnifier view ([9c7d2fa](9c7d2fab5f))
* add debug indicator for custom crop region (dev only) ([9c89aad](9c89aadb17))
* add detailed zoom decision debug panel ([cb57f15](cb57f1585a))
* add dev-only crop tool for custom map region cropping ([855e5df](855e5df2c0))
* add download and share buttons to shared worksheet viewer ([9b8947a](9b8947a198))
* add dynamic layout preview component for orientation selection ([8df62d6](8df62d6a45))
* add dynamic operator icon to tab navigation ([b6ff995](b6ff995a8c))
* add exponential zoom scaling for sub-pixel regions ([101213b](101213ba1c))
* add fancy QR codes with abacus logo throughout app ([ebcabf9](ebcabf9bb9))
* add give up with zoom animation for Know Your World ([94cff43](94cff4374f))
* add gold scrim overlay and improve precision mode messaging ([4b20d07](4b20d0753f))
* add interactive world map continent selector ([245005c](245005c8ec))
* add Know Your World geography quiz game ([25e24a7](25e24a7cbc))
* add mobile drawer and detailed summary for shared worksheets ([0a35e70](0a35e70e28))
* add ngrok tunnel to dev server for HTTPS testing ([ab2bfde](ab2bfde9c2))
* add per-country coloring and individual region clicks to continent selector ([2e9f409](2e9f409f26))
* add per-page worksheet generation API ([6398fbe](6398fbead9))
* add Pointer Lock API for precision mode to prevent edge issues ([4d5953d](4d5953d034))
* add precision controls for tiny regions in Know Your World ([3bf127f](3bf127f344))
* add precision mode system with pixel grid visualization ([53e9041](53e90414a3))
* add prev/next navigation buttons to mixed mode mini skill panes ([498df2c](498df2ca5a))
* add problem space validation to warn about duplicate risk ([0b8c180](0b8c1803ff))
* add responsive mobile drawer with draggable settings button ([fc1d7fc](fc1d7fcbd6))
* add responsive page button layout with dynamic dropdown ([3f33cd1](3f33cd1924))
* add shared worksheet viewer with open-in-editor functionality ([4b8b3ee](4b8b3ee532))
* add single-page worksheet preview API endpoint ([10e97db](10e97db78a))
* add skill configuration system with interactive 2D difficulty plot ([7fbc743](7fbc743c4c)), closes [#9333](https://github.com/antialias/soroban-abacus-flashcards/issues/9333) [#10b981](https://github.com/antialias/soroban-abacus-flashcards/issues/10b981)
* add smooth fade-in animation for 404 message text changes ([e88380a](e88380a48d))
* add split-action share button with copy shortcut ([085d200](085d200da4))
* add themed backgrounds and enhanced styling to 404 page ([dd14062](dd14062112))
* add visible grab tab to worksheet panel resize handle ([288e6ed](288e6ed878))
* add visual debugging for zoom importance scoring ([e60a2c0](e60a2c09c0))
* add visual grab tab to resize handle with rounded corners ([6e55d5a](6e55d5add7))
* add visual warnings to page selector buttons ([5a87799](5a8779969c))
* add worksheet generation core logic and helpers ([163517d](163517db7d))
* add worksheet sharing infrastructure with database persistence ([7b4c7c3](7b4c7c3fb6))
* add worksheet studio with comprehensive features ([d5672bd](d5672bdddf))
* apply skill-specific scaffolding and fix mini card heights ([ee90182](ee90182ff2))
* **blog:** add subtraction and multi-digit worksheet blog posts ([dd9587f](dd9587f8cd))
* calculate zoom based on region under cursor, target 15% area ([6736336](6736336317))
* convert operator selection to checkboxes with required validation ([c997c4a](c997c4a7ba))
* create unified difficulty interface with 2-tab selector ([0b7382f](0b7382f1b6))
* enable production source maps for easier debugging ([d992e98](d992e98d77))
* enhance scaffolding tab with live preview and resolved display rules ([9a5a0d4](9a5a0d4e3c))
* **help-system:** add focus areas for skills needing reinforcement ([871390d](871390d8e1))
* **help-system:** add schema for progressive help and feedback loop ([41c4603](41c46038d8))
* **help-system:** add usePracticeHelp hook and skill extraction ([0b1ad1f](0b1ad1f896))
* **help-system:** integrate PracticeHelpPanel into ActiveSession ([373ec34](373ec34e46))
* hide easter egg hint until first discovery ([c2c7153](c2c71531ae))
* implement binary search for optimal zoom level ([1a54f09](1a54f09814))
* implement fit-crop-with-fill for custom map crops ([b6569ed](b6569ed4e1))
* implement lazy loading for worksheet preview with cursor pagination ([8b3d019](8b3d019652))
* implement lazy loading for worksheet preview with cursor pagination ([2a7d67d](2a7d67db58))
* improve shared worksheet viewer UX and multi-page support ([1c10a82](1c10a82c78))
* improve tab navigation layout and add pages to layout button ([926a029](926a029ff8))
* improve worksheet preview placeholder with cartoonish grid layout ([57fb99a](57fb99af63))
* increase max super zoom to 120x for ultra-tiny regions ([9b782be](9b782beabf))
* increase max zoom to 1000x with detailed debug logging ([a6be05f](a6be05f8c1))
* **know-your-world:** add 'H' keyboard shortcut for hint ([cdc9451](cdc94514d9))
* **know-your-world:** add adaptive hint cycling for struggling users ([5440250](54402501e5))
* **know-your-world:** add celebration animations for found regions ([3b9d6b0](3b9d6b0fdf))
* **know-your-world:** add device capability hooks and improve mobile support ([c502a4f](c502a4fa92))
* **know-your-world:** add drill-down map selector and improve setup UI ([a6f8dbe](a6f8dbe474))
* **know-your-world:** add filter tabs for size, importance, and population ([6c3c0ac](6c3c0ac70e))
* **know-your-world:** add fire tracer animation for learning mode takeover ([1e6153e](1e6153ee8b))
* **know-your-world:** add hint system, pointer lock buttons, and mobile magnifier support ([55e480c](55e480c03b))
* **know-your-world:** add hints for Europe and Africa regions ([46e5c6b](46e5c6b99b))
* **know-your-world:** add hot/cold audio feedback for cursor proximity ([69813e9](69813e92a2))
* **know-your-world:** add hot/cold debug panel and production debug mode ([493313a](493313a3bb))
* **know-your-world:** add hot/cold feedback for mobile magnifier ([824325b](824325b843))
* **know-your-world:** add interaction state machine foundation ([e4d6748](e4d6748d70))
* **know-your-world:** add Learning mode and fix hints before name unlock ([fc87808](fc87808b40))
* **know-your-world:** add learning mode takeover animation and fix give-up sequence ([3fd8472](3fd8472e68))
* **know-your-world:** add map zoom preview, remove study time feature ([57dd61b](57dd61b994))
* **know-your-world:** add missing island hints and revise all hints ([8b13b5a](8b13b5a455))
* **know-your-world:** add mobile cursor sharing and fix multi-device coop mode ([2ce5e18](2ce5e180b7))
* **know-your-world:** add mobile virtual keyboard and space-skipping ([5318d0d](5318d0dd89))
* **know-your-world:** add multiplayer cursor sharing and fix map viewport ([c3b94be](c3b94bea3d))
* **know-your-world:** add puzzle piece fly-to-map animation for learning mode ([7c49652](7c496525e9))
* **know-your-world:** add range thermometer for region size selection ([c7c4e7c](c7c4e7cef3))
* **know-your-world:** add region shape silhouette to learning takeover ([ebe07e3](ebe07e358f))
* **know-your-world:** add session-based give-up voting and fix cursor emojis ([bb2d6fc](bb2d6fc7d8))
* **know-your-world:** add speech announcements and compass-style crosshairs ([e0b762e](e0b762e3ee))
* **know-your-world:** add speech synthesis for hints with auto-hint/auto-speak ([cd841ff](cd841ff7dc))
* **know-your-world:** add Strudel-based music system ([7dab07b](7dab07b3a7))
* **know-your-world:** add SVG path geometry helpers for future use ([ea141f0](ea141f04f6))
* **know-your-world:** add turn-based restrictions for letter typing ([45730bb](45730bb4db))
* **know-your-world:** align guidance UI with assistance levels ([7e7a8dc](7e7a8dc1e8))
* **know-your-world:** auto-enable hot/cold for learning mode ([dcc32c2](dcc32c288f))
* **know-your-world:** enhance hint audio and region name display ([e6f58bf](e6f58bfd93))
* **know-your-world:** fix magnifier outline aspect ratio and add visual debug toggle ([ac915f2](ac915f2065))
* **know-your-world:** full-screen layout with squish-through pointer lock escape ([1729418](1729418dc5))
* **know-your-world:** implement empirical scale measurement for 1:1 magnifier tracking ([39886e8](39886e859c))
* **know-your-world:** improve magnifier UX and hide abacus on games ([fa1514d](fa1514d351))
* **know-your-world:** improve mobile magnifier controls and animations ([4449fb1](4449fb19b4))
* **know-your-world:** improve mobile magnifier with adaptive zoom and select button ([60cf98e](60cf98e77a))
* **know-your-world:** improve region size filter layout ([558d369](558d369ba0))
* **know-your-world:** improve setup screen UX ([dc4d621](dc4d62195b))
* **know-your-world:** improve takeover UI and fix celebration sound bug ([a8c6b84](a8c6b84855))
* **know-your-world:** live crop updates and safe zone improvements ([3f4691e](3f4691e8a3))
* **know-your-world:** make magnifier lazy - only move when cursor obscured ([ac82564](ac82564eac))
* **know-your-world:** make magnifier size responsive to aspect ratio ([5920cb4](5920cb4dc3))
* **know-your-world:** match setup phase map positioning with gameplay ([b030558](b0305581f9))
* **know-your-world:** move region size filters inside map preview ([81301ab](81301ab148))
* **know-your-world:** move start button below settings controls ([a05c4ca](a05c4ca5bf))
* **know-your-world:** Phase 2 - integrate useMagnifierZoom hook ([8ce878d](8ce878d03e))
* **know-your-world:** responsive setup + travel-themed start button ([02762fa](02762fad81))
* **know-your-world:** separate region filtering from assistance level ([9499e4e](9499e4e8b5))
* **know-your-world:** show magnifier on mobile drag gesture ([a02a710](a02a7108e9))
* **know-your-world:** speak country names in user's locale ([426a1e6](426a1e6868))
* **know-your-world:** sync letter confirmation across multiplayer sessions ([655660f](655660f7cf))
* **know-your-world:** unified region selector with inline list on desktop ([d329d80](d329d80399))
* **know-your-world:** unify setup and gameplay UI positions ([141a506](141a506739))
* **know-your-world:** unify setup UI positions with gameplay ([c1a0485](c1a0485b1d))
* **know-your-world:** wire interaction state machine to MapRenderer ([7e55953](7e55953eee))
* make 404 page abacus hero-sized and responsive ([41de252](41de25238f))
* make resize handle grab tab fully draggable with rounded corners ([be40f70](be40f70bc6))
* make scaffolding and preview collapsible ([804fb1a](804fb1a2f6))
* make super zoom threshold configurable and increase to 3px ([d7ce474](d7ce474a51))
* make zoom transitions 4x slower for smoother experience ([ca752bd](ca752bd0aa))
* move difficulty parameters into Smart mode ([4b66758](4b667587f8))
* move layout controls to OrientationPanel with toggles ([995966f](995966ffbc))
* operator-specific scaffolding for mixed mastery mode ([4d7d000](4d7d000046))
* optimize problem generation and add duplicate warning system ([11c46c1](11c46c1b44))
* pause zoom animation at precision mode threshold ([c4989b3](c4989b3ab0))
* pause/resume zoom animation at precision mode threshold ([bdf59e5](bdf59e571d))
* pause/resume zoom animation at precision mode threshold ([4687820](4687820d8a))
* persist seed and prngAlgorithm for exact problem reproducibility ([8cb2209](8cb2209d84))
* **practice:** add dark mode support and fix doubled answer digits ([026993c](026993cb05))
* **practice:** add progressive help overlay with proper positioning ([9a4ab82](9a4ab8296e))
* **practice:** add session HUD with tape-deck controls and PageWithNav ([b19c6d0](b19c6d0eca))
* **practice:** add smooth problem transition animation ([b12112e](b12112e8da))
* **practice:** add student onboarding and offline sync features ([b52f054](b52f0547af))
* **practice:** add three-part daily practice session system ([5855438](585543809a))
* **practice:** improve help UX with coach hints and simplified UI ([19169ad](19169ad9fe))
* **practice:** integrate progressive help with decomposition display ([804d937](804d937dd9))
* redesign shared worksheet viewer with read-only studio and proper error handling ([23dccc0](23dccc0ef3))
* remove all easter egg hints from 404 page ([1756182](17561829ef))
* remove redundant navigation buttons from 404 page ([e5262e5](e5262e5007))
* show magnifier only when current target region needs magnification ([996c973](996c973774))
* show magnifier only when target region needs it ([c6997ac](c6997ac9a7))
* show visual feedback for auto-resolved scaffolding values ([fbe776a](fbe776ac09))
* smooth cursor dampening transitions with react-spring ([66544dc](66544dc7dd))
* **thermometer:** add "only" buttons to quickly select single category ([623f882](623f882075))
* **worksheets:** add 3x scale effect to thrown dice ([920a855](920a855eb5))
* **worksheets:** add draggable dice easter egg with physics ([b8e66df](b8e66dfc17))
* **worksheets:** add duplicate risk warnings to page selector UI ([1d8dceb](1d8dceb55b))
* **worksheets:** add foundational steps to progression path ([7e6f99b](7e6f99b78c))
* **worksheets:** add QR codes with share codes for easy worksheet sharing ([a0e73d9](a0e73d971b))
* **worksheets:** add shuffle button with animated dice icon ([f97efb5](f97efb5c94))
* **worksheets:** add viewport edge ricochet to dice physics ([c6db7dc](c6db7dcfa2))
* **worksheets:** enhance dice throw physics for natural feel ([047a960](047a960567))
* **worksheets:** restore mastery progression UI with 3-way mode selector ([26a0885](26a08859d7))
* **worksheets:** smooth dice rotation settle to final face ([d00c707](d00c70750e))
* **worksheets:** upgrade to 3D dice with random rotation animation ([3cd5e49](3cd5e4992b))

### Performance Improvements

* add spatial filtering to skip distant regions ([8cb4c88](8cb4c88bef))
* cache polygon conversions to fix performance regression ([348ce8f](348ce8f314))
* **know-your-world:** memoize state machine return value and remove debug logging ([d85b976](d85b976f8b))
* reduce retry limit from 3000 to 100 in problem generators ([08fef59](08fef59cc5))

### Reverts

* **know-your-world:** undo premature extractions, restore working state ([f0bf205](f0bf2050d3))
* remove ngrok and LAN IP detection ([0040b57](0040b57829))
 		2025-12-08 17:50:10 +00:00
.claude
…
.github/workflows fix: upgrade to Node.js 20 to resolve ES module import issues 2025-11-23 12:44:02 -06:00
apps/web chore: miscellaneous updates and documentation 2025-12-08 11:40:59 -06:00
docs
…
nas-deployment
…
out fix: prevent database imports from being bundled into client code 2025-10-10 11:40:46 -05:00
packages chore(abacus-react): release v2.15.0 [skip ci] 2025-12-08 17:50:10 +00:00
scripts feat: add development tooling and comprehensive setup 2025-09-14 08:03:53 -05:00
test_svg_inactive_beads.svg
…
test_svg_smaller_gaps.svg
…
tests
…
.dockerignore fix: prevent undefined displayRules error in worksheet generator 2025-11-07 13:01:54 -06:00
.gitignore
…
.mcp.json
…
.releaserc.json
…
ARCADE_CHARACTER_INTEGRATION_PLAN.md
…
ARITHMETIC_CHALLENGES_PLAN.md
…
CHANGELOG.md feat(know-your-world): live crop updates and safe zone improvements 2025-11-28 19:46:23 -06:00
CONTRIBUTING.md
…
DEPLOYMENT.md
…
DESIGN.md
…
DEVELOPMENT.md
…
Dockerfile fix: upgrade to Node.js 20 to resolve ES module import issues 2025-11-23 12:44:02 -06:00
INSTALL.md
…
Makefile
…
PLACE_VALUE_REFACTOR_PLAN.md
…
PRACTICE_PROBLEM_SYSTEM.md
…
PROGRESSIVE_INSTRUCTION_PLAN.md
…
README.md feat(practice): integrate progressive help with decomposition display 2025-12-07 08:56:35 -06:00
REBUILD_CHECKLIST.md
…
demo_heaven_bead_fix.html
…
demo_heaven_bead_gap_fixed.html
…
demo_heaven_bead_gap_fixed.pdf
…
demo_heaven_bead_gap_fixed_linear.pdf
…
generate_complete_games_website.py
…
generate_samples.sh
…
guest-auth-plan.md
…
hero_showcase.html
…
package.json
…
pnpm-lock.yaml chore: miscellaneous updates and documentation 2025-12-08 11:40:59 -06:00
pnpm-workspace.yaml
…
pyproject.toml
…
pytest.ini
…
requirements-api.txt
…
requirements.txt
…
server-persistence-plan.md
…
setup-dev.sh
…
test-templates-integration.js
…
test_active_bead_gaps.html
…
test_active_bead_gaps_fixed.html
…
test_active_heaven_beads.html
…
test_adjacent_fixed.html
…
test_adjacent_spacing.html
…
test_adjacent_spacing.pdf
…
test_adjacent_spacing_linear.pdf
…
test_all_adjacent_spacing.html
…
test_all_digits_physical.html
…
test_all_digits_physical.pdf
…
test_all_digits_physical_linear.pdf
…
test_alternating_colors.html
…
test_alternating_colors_fixed.html
…
test_animations.html
…
test_arithmetic_complete.html
…
test_arithmetic_complete.pdf
…
test_balanced_gaps.html
…
test_beautiful_ui.html
…
test_beautiful_ui.pdf
…
test_better_spacing.html
…
test_better_spacing.pdf
…
test_better_spacing_linear.pdf
…
test_borderless_input.html
…
test_clean.html
…
test_closer_gaps.html
…
test_colorblind.html
…
test_companion.pdf
…
test_complete_guide.html
…
test_complete_guide.pdf
…
test_debug_prefix.html
…
test_debug_prefix.pdf
…
test_equal_gaps.html
…
test_equal_gaps.pdf
…
test_equal_gaps_final.html
…
test_equal_gaps_linear.pdf
…
test_expanded_heaven_gap.html
…
test_final_input_and_cards.html
…
test_final_larger_abacus.html
…
test_fixed_syntax.html
…
test_heaven_above_bar.html
…
test_heaven_above_bar.pdf
…
test_heaven_above_bar_linear.pdf
…
test_heaven_beads.html
…
test_heaven_beads.pdf
…
test_heaven_beads_active.html
…
test_heaven_beads_fixed.html
…
test_heaven_beads_fixed.pdf
…
test_heaven_beads_fixed_linear.pdf
…
test_heaven_beads_linear.pdf
…
test_heaven_earth_colors.html
…
test_heaven_earth_spans.html
…
test_heaven_way_up_top.html
…
test_higher_heaven_beads.html
…
test_improved_print.html
…
test_improved_print.pdf
…
test_inactive_separation.html
…
test_individual_digit_colors.html
…
test_large_cards_fixed_input.html
…
test_larger_abacus.html
…
test_larger_sorting_game.html
…
test_long_number_colors.html
…
test_maximum_heaven_gap.html
…
test_maximum_heaven_gap.pdf
…
test_maximum_heaven_gap_linear.pdf
…
test_memory_fix.html
…
test_memory_fix.pdf
…
test_memory_grid_hiding.html
…
test_memory_grid_hiding.pdf
…
test_memory_partial_hiding.html
…
test_memory_partial_hiding.pdf
…
test_mnemonic_colors.html
…
test_monochrome_no_spans.html
…
test_multiple_place_values.html
…
test_new_challenge_layout.html
…
test_pdf_bead_gaps.pdf
…
test_pdf_bead_gaps_fixed.pdf
…
test_pdf_bead_gaps_fixed_linear.pdf
…
test_pdf_bead_gaps_linear.pdf
…
test_pdf_direct.html
…
test_pdf_direct.pdf
…
test_pdf_inactive_beads.pdf
…
test_pdf_inactive_beads_linear.pdf
…
test_pdf_smaller_gaps.pdf
…
test_pdf_smaller_gaps_linear.pdf
…
test_penalty_scoring.html
…
test_physical_abacus_logic.html
…
test_place_value_colors.html
…
test_place_value_colors_fixed.html
…
test_prefix_conflicts.html
…
test_prefix_conflicts.pdf
…
test_print_fix.html
…
test_print_fix.pdf
…
test_print_fixed.html
…
test_print_fixed.pdf
…
test_relative_to_reckoning_bar.html
…
test_rod_bounds.html
…
test_rod_bounds.pdf
…
test_rod_bounds_hidden.html
…
test_rod_bounds_linear.pdf
…
test_scaling.html
…
test_sectioned_layout.html
…
test_sectioned_layout.pdf
…
test_simple_equal_gaps.html
…
test_smart_input.html
…
test_sorting_buttons_fix.html
…
test_tutorial_complete.html
…
test_tutorial_complete.pdf
…
test_viewport_aware_cards.html
…
test_welcome_intro.html
…
test_welcome_intro.pdf
…
test_zero_hidden.html
…
turbo.json
…

README.md

🧮 Soroban Flashcard Generator

Master the Ancient Art of Mental Math

Colorful Soroban showing 987,654,321
Transform numbers into beautiful, interactive learning experiences

The ultimate toolkit for learning soroban (Japanese abacus) calculation
🎯 Perfect for students, teachers, and mental math enthusiasts
🚀 From zero to calculation ninja in record time
🎨 Stunning visuals meet ancient wisdom

Create gorgeous flashcards, interactive web games, and immersive quizzes that make learning soroban addictive. Whether you're teaching a classroom or mastering mental math yourself, this generator transforms traditional number learning into a vibrant, engaging adventure.

🔥 What makes this special:

  • Visual perfection: Crystal-clear soroban representations with authentic bead positioning
  • Game-changing interactivity: Memory challenges, sorting games, and smart input systems
  • Universal compatibility: Generate PDFs, web apps, PNGs, SVGs - whatever you need
  • Colorblind-friendly: Thoughtfully designed palettes ensure everyone can learn
  • Instant deployment: One command creates complete learning environments

🎨 Visual Gallery

Experience the Beauty of Mathematical Precision

Nature palette soroban
🌿 Nature Palette
Earth tones for focused learning 		Colorblind-friendly soroban
👁️ Universal Access
Colorblind-friendly brilliance 		Mnemonic color soroban
🧠 Memory Master
Colors that stick in your mind

Each bead precisely positioned, every color carefully chosen, all interactions thoughtfully designed.

Examples

Soroban showing 123
Soroban (Front) 		Numeral 123
Numeral (Back) 		Place-value colored 456
Place-Value Colors 		Colored numeral 456
Colored Numerals

Bead Shapes

Diamond beads
Diamond (Realistic) 		Circle beads
Circle (Traditional) 		Square beads
Square

Layouts and Options

6 cards per page
6 Cards Per Page 		12 cards per page
12 Cards Per Page
Counting by 5s
Skip Counting by 5s 		Hidden inactive beads
Hidden Inactive Beads

Printing Features

Cutting guides
Cutting Guides
Full-page guides for accurate card separation 		Cutting and registration marks
With Registration Marks
Alignment marks for duplex printing verification

Output Formats

📱 Interactive Web Flashcards (--format web)

Generate self-contained HTML files with advanced interactive features:

# Generate interactive web flashcards
python3 src/generate.py --format web --range 0-99 --output flashcards.html

# Try the quiz mode
python3 src/generate.py --format web --range 0-50 --shuffle

Web Features:

  • 🃏 Digital Flashcards: Hover to reveal numbers, click to flip cards
  • 🧠 Timed Quiz Mode: Configurable display times (0.5-10 seconds), multiple card counts (5, 10, 15, 25, All)
  • 📊 Smart Scoring: Fair scoring algorithm, progress tracking, detailed results
  • 🎯 Sorting Challenge: Drag-and-drop number sorting with gap-filling logic
  • 🎮 Matching Pairs: Memory game matching abacus patterns with numerals
    • Single & two-player modes with competitive scoring
    • Multiple grid sizes (3×4, 4×4, 4×6, 5×6) for different skill levels
    • Turn-based timers and player indicators for multiplayer games
    • Efficiency-based medal system (Gold/Silver/Bronze achievements)
  • 📱 Responsive Design: Works on desktop, tablet, and mobile
  • 🖨️ PDF Integration: Automatically suggests high-quality PDF format when printing is attempted
  • ♿ Accessible: Keyboard navigation, semantic HTML, ARIA labels
  • 🎨 Full Customization: All color schemes, bead shapes, and display options supported

📄 Vector PDF (--format pdf)

High-quality vector PDFs optimized for duplex printing:

# Standard PDF with cut marks
python3 src/generate.py --format pdf --range 0-99 --cut-marks --registration

PDF Features:

  • Pure vector graphics for crisp output at any scale
  • Duplex printing alignment with registration marks
  • Cutting guides for precise card separation
  • Embedded fonts ensure consistent output

🖼️ PNG/SVG Images (--format png, --format svg)

Individual card images for digital use or custom layouts:

# Generate PNG cards at high resolution
python3 src/generate.py --format png --range 1-10 --dpi 300 --transparent

# Generate SVG cards for web use
python3 src/generate.py --format svg --range 0-99 --separate

Image Features:

  • High-resolution PNG (configurable DPI)
  • Scalable SVG with embedded CSS
  • Transparent backgrounds supported
  • Separate front/back organization

Features

🎓 Learning & Teaching Tools

  • 🧠 Interactive Quiz Mode: Timed flashcard quizzes with configurable display times and scoring
  • 🎯 Sorting Challenges: Drag-and-drop number sorting games with intelligent gap-filling
  • 🎮 Matching Pairs Game: Memory challenges matching soroban patterns with numerals
    • Single Player: Focus mode with efficiency scoring and medal achievements
    • Two Player: Competitive multiplayer with turn timers and player tracking
    • Adaptive Difficulty: 4 grid sizes (6-30 pairs) scaling with skill level
    • Smart Validation: Prevents invalid moves, guides learning progression
  • 📊 Progress Tracking: Real-time feedback, scoring, and performance analytics
  • 📱 Multi-Device Support: Responsive design works on desktop, tablet, and mobile

🎨 Visual Customization

  • 🎯 Pure vector graphics - Crisp output at any scale, all formats
  • 🎨 Color schemes - Educational colors for place-value, heaven-earth, alternating
  • 🌈 Colored numerals - Match numeral colors to bead colors for reinforcement
  • 🔷 Customizable beads - Diamond (realistic), circle, or square shapes
  • 🔀 Minimalist mode - Hide inactive beads for cleaner displays

📋 Flexible Content

  • 🔢 Flexible ranges - Any range (0-9999+) or custom lists (1,2,5,10,20,50,100)
  • 📈 Skip counting - Count by 2s, 5s, 10s, or any increment
  • 🎲 Shuffling - Randomize with optional seeds for reproducible builds
  • 📊 Smart scaling - Automatic column management and font sizing

🖨️ Print & Production

  • 📏 Configurable layouts - 1 to 30+ cards per page with automatic scaling
  • 🖨️ Duplex printing ready - Automatic front/back alignment for double-sided printing
  • ✂️ Cutting guides - Full-page guides and registration marks for accurate separation
  • 🔤 Embedded fonts - Bundled DejaVu Sans for consistent cross-platform output

🔧 Integration & Formats

  • 📱 Web HTML - Self-contained interactive flashcards with quiz modes
  • 📄 Vector PDF - High-quality print-ready documents
  • 🖼️ PNG/SVG - Individual card images for digital use
  • 📦 Node.js/TypeScript - Clean API for web applications
  • 🌐 REST API - FastAPI server for web services
  • ⚙️ CLI Interface - Powerful command-line tool with extensive options

Quick Start

Prerequisites

  • macOS (tested on latest versions)
  • Python 3 (included with macOS)
  • Typst (PDF generation engine)
  • qpdf (optional, for linearization)

Installation

# Install dependencies
make install

# Or manually:
brew install typst qpdf
pip3 install pyyaml

Generate Flashcards

# Generate default set (0-9)
make

# Generate from config file
python3 src/generate.py --config config/0-99.yaml

# Custom range
python3 src/generate.py --range 0-99

# Custom list of numbers
python3 src/generate.py --range "1,2,5,10,20,50,100"

# With shuffle
python3 src/generate.py --range 0-99 --shuffle --seed 42

📚 Component Documentation

Explore our comprehensive component documentation and interactive examples:

🎮 Interactive Learning Games

The web format includes three immersive learning experiences designed to make soroban mastery engaging and fun:

🧠 Memory Quiz Challenge

Test your number recognition skills with timed flashcard quizzes:

  • Adaptive Timing: 0.5-10 second display windows
  • Flexible Difficulty: 5, 10, 15, 25 cards or full deck
  • Smart Scoring: Accounts for difficulty and accuracy
  • Progress Tracking: Real-time feedback and performance analytics

🎯 Sorting Master

Develop number sense through drag-and-drop sorting challenges:

  • Intelligent Gap-Filling: Place cards in the correct sequence
  • Visual Feedback: Immediate validation and hints
  • Scalable Difficulty: Choose your challenge level
  • Educational Design: Reinforces number relationships

🎮 Matching Pairs Arena

Memory game combining visual pattern recognition with numerical understanding:

Single Player Mode:

  • 🏆 Medal System: Gold (≤1.5× pairs), Silver (≤2× pairs), Bronze (≤3× pairs)
  • 📏 Four Grid Sizes: 3×4 (6 pairs), 4×4 (8 pairs), 4×6 (12 pairs), 5×6 (15 pairs)
  • ⚡ Efficiency Scoring: Rewards optimal play and quick thinking
  • 🎯 Smart Validation: Only allows valid matches (abacus ↔ numeral)

Two Player Mode:

  • 👥 Competitive Multiplayer: Turn-based gameplay with score tracking
  • ⏱️ Turn Timers: Optional 15s/30s/60s time limits with visual countdown
  • 🏆 Player Indicators: Color-coded badges show who found each match
  • 🚀 First Move Grace: Timer waits for first card flip to begin counting
  • 🎨 Visual Clarity: De-emphasized matched cards guide continued play

Technical Features:

  • 📱 Responsive Design: Scales perfectly on all devices without scrolling
  • 🔄 One-Click Start: Integrated mode and grid selection
  • 🎨 Kid-Friendly UX: Clear visual feedback prevents confusion
  • ♿ Accessible: Keyboard navigation and semantic HTML

Configuration

Using Configuration Files

Create a YAML or JSON file with your preferences:

range: "0-99"
cards_per_page: 6
paper_size: "us-letter"
orientation: "portrait"
margins:
  top: "0.5in"
  bottom: "0.5in"
  left: "0.5in"
  right: "0.5in"
gutter: "5mm"
show_cut_marks: true
show_registration: true
font_family: "DejaVu Sans"
font_size: "48pt"
columns: auto
show_empty_columns: false
shuffle: false
seed: 42 # For deterministic shuffling

Command-Line Options

python3 src/generate.py [OPTIONS]

Options:
  --config, -c FILE           Configuration file (JSON or YAML)
  --range, -r RANGE          Number range (e.g., "0-99") or list (e.g., "1,2,5")
  --step, -s N               Step/increment for ranges (e.g., 2 for even numbers)
  --cards-per-page N         Cards per page (default: 6, supports 1-30+)
  --paper-size SIZE          Paper size (default: us-letter)
  --orientation ORIENT       Page orientation (portrait/landscape)
  --margins T,R,B,L          Margins (e.g., "0.5in,0.5in,0.5in,0.5in")
  --gutter SIZE              Space between cards (default: 5mm)
  --shuffle                  Shuffle the numbers
  --seed N                   Random seed for deterministic shuffle
  --cut-marks                Show cut marks
  --registration             Show registration marks for alignment
  --font-family FONT         Font family (default: DejaVu Sans)
  --font-size SIZE           Font size (default: 48pt, auto-scales)
  --columns N                Soroban columns (auto or number)
  --show-empty-columns       Show leading empty columns
  --hide-inactive-beads      Hide inactive beads (show only active)
  --bead-shape SHAPE         Bead shape (diamond/circle/square)
  --color-scheme SCHEME      Color scheme (monochrome/place-value/heaven-earth/alternating)
  --colored-numerals         Color numerals to match bead colors
  --scale-factor N           Manual scale adjustment (0.1-1.0, default: 0.9)
  --output, -o FILE          Output PDF path (default: out/flashcards.pdf)
  --linearize                Create linearized PDF (default: true)

Soroban Representation

The soroban is rendered with:

  • 1 heaven bead (worth 5) per column
  • 4 earth beads (worth 1 each) per column
  • Active beads shown in black, moved toward the reckoning bar
  • Inactive beads shown in light gray, away from the bar
  • Columns represent place values (ones, tens, hundreds, etc.)

Column Display Options

  • columns: auto - Shows minimal columns needed
  • columns: 3 - Always shows 3 columns (e.g., for 0-999)
  • show_empty_columns: true - Shows leading zeros
  • show_empty_columns: false - Suppresses leading zeros

Print Settings

For Best Results

  1. Paper: US Letter (8.5" × 11") or A4
  2. Margins: Default 0.5" works with most printers
  3. Duplex: Long-edge binding, automatic duplex
  4. Cut marks: Enable with --cut-marks for easier cutting
  5. Registration: Enable with --registration for alignment verification

Duplex Printing

The PDFs are specifically formatted for double-sided printing:

  • Odd pages (1, 3, 5...): Soroban bead diagrams (front of cards)
  • Even pages (2, 4, 6...): Arabic numerals (back of cards)
  • Pages are properly ordered for long-edge binding (standard duplex)
  • Back sides are horizontally mirrored to align correctly when flipped

To print double-sided:

  1. Open the PDF in your viewer
  2. Select Print → Two-Sided → Long-Edge Binding
  3. The printer will automatically place numerals on the back of each soroban diagram

Sample Configurations

  • config/default.yaml - Basic 0-9 set
  • config/0-99.yaml - Two-digit numbers with cut marks
  • config/3-column-fixed.yaml - Three-digit numbers, fixed width
  • config/minimal-beads.yaml - Hide inactive beads for clarity
  • config/circle-beads.yaml - Traditional circular beads
  • config/place-value-colors.yaml - Place value color coding
  • config/colored-numerals.yaml - Colored numerals matching beads
  • config/count-by-5s.yaml - Skip counting by 5s

Project Structure

soroban-abacus-flashcards/
├── src/
│   ├── generate.py            # Main CLI tool (all formats)
│   ├── web_generator.py       # Interactive web flashcards with quiz modes
│   ├── bridge.py              # Node.js integration bridge
│   ├── api.py                 # FastAPI REST server
│   └── generate_examples.py   # Example generation utilities
├── templates/
│   └── flashcards.typ         # Typst template with soroban rendering
├── config/                    # Preset configurations
│   ├── default.yaml           # Basic 0-9 set
│   ├── 0-99.yaml             # Two-digit numbers with cut marks
│   ├── place-value-colors.yaml # Educational color coding
│   ├── colored-numerals.yaml  # Matching numeral colors
│   ├── minimal-beads.yaml     # Hide inactive beads
│   ├── circle-beads.yaml      # Traditional circular beads
│   ├── count-by-5s.yaml       # Skip counting by 5s
│   └── 3-column-fixed.yaml    # Fixed-width three-digit display
├── tests/
│   ├── test_generation.py     # Core generation tests
│   ├── test_web_generation.py # Web format tests
│   ├── test_quiz_functionality.py # Interactive quiz tests
│   ├── test_config.py         # Configuration parsing tests
│   └── test_visual.py         # Visual output validation
├── client/                    # Integration libraries
│   ├── node/                  # Node.js/TypeScript wrapper
│   ├── typescript/            # Browser TypeScript client
│   └── browser/               # Browser-based implementation
├── fonts/
│   ├── DejaVuSans.ttf        # Bundled font
│   └── DejaVuSans-Bold.ttf   # Bold variant
├── docs/
│   └── images/               # Example images for README
├── out/                      # Generated outputs (created on first run)
│   ├── *.pdf                # PDF flashcards
│   ├── *.html               # Interactive web flashcards
│   ├── png/                 # PNG card images
│   └── svg/                 # SVG card images
├── Makefile                  # Build automation
└── README.md                # This file

Design Notes

Soroban Number Mapping

Numbers are decomposed into heaven (5s) and earth (1s) beads:

  • 7 = 1 heaven bead (5) + 2 earth beads (2×1)
  • 23 = Tens: 4 earth beads (4×1), Ones: 3 earth beads (3×1)
  • 156 = Hundreds: 1 heaven + 0 earth, Tens: 1 heaven + 0 earth, Ones: 1 heaven + 1 earth

Duplex Alignment

  • Front cards are laid out left-to-right, top-to-bottom
  • Back cards are mirrored horizontally for long-edge binding
  • Registration marks (optional) help verify alignment
  • Safe margins ensure content isn't lost when cutting

Vector Graphics

All elements are rendered as vectors using Typst's drawing primitives:

  • Beads are vector circles with stroke
  • Rods and reckoning bar are vector rectangles
  • No rasterization ensures crisp output at any scale

Troubleshooting

"typst command not found"

Run make install or brew install typst

"qpdf command not found"

PDF will generate but won't be linearized. Install with brew install qpdf

Fonts not embedding

Ensure the fonts/ directory contains the DejaVu TTF files

Misaligned duplex printing

  • Check printer duplex settings (should be long-edge)
  • Enable registration marks with --registration
  • Verify margins match your printer's capabilities

Examples

Quick Start Examples

# Generate interactive web flashcards (try the quiz!)
python3 src/generate.py --format web --range 0-20 --shuffle

# Generate print-ready PDF with cutting guides
python3 src/generate.py --format pdf --range 0-99 --cut-marks --registration

# Generate high-res PNG cards for digital use
python3 src/generate.py --format png --range 1-10 --dpi 300 --transparent

# Generate place-value colored cards for teaching
python3 src/generate.py --format web --range 0-50 \
  --color-scheme place-value --colored-numerals

# Generate minimal-style cards (hide inactive beads)
python3 src/generate.py --format web --range 0-25 --hide-inactive-beads

# Generate skip-counting practice (count by 5s)
python3 src/generate.py --format web --range 0-100 --step 5

Development & Testing

# Generate samples
make samples

# Quick test
make test

# Clean all outputs
make clean

# Show help
make help

Node.js/TypeScript Integration

Installation

cd client/node
npm install

Usage Example

import { SorobanGenerator } from "./soroban-generator-bridge";

async function generateFlashcards() {
  const generator = new SorobanGenerator();

  // Generate with clean function interface - no CLI args!
  const result = await generator.generate({
    range: "0-99",
    cardsPerPage: 6,
    colorScheme: "place-value",
    coloredNumerals: true,
    showCutMarks: true,
  });

  // Get PDF as Buffer
  const pdfBuffer = Buffer.from(result.pdf, "base64");

  // Save to file or send to client
  await fs.writeFile("flashcards.pdf", pdfBuffer);
}

Express.js Integration

import express from "express";
import { SorobanGenerator } from "./soroban-generator-bridge";

const app = express();
const generator = new SorobanGenerator();

app.post("/api/flashcards", async (req, res) => {
  // Direct function call - no shell commands!
  const result = await generator.generate(req.body);
  const pdfBuffer = Buffer.from(result.pdf, "base64");

  res.contentType("application/pdf");
  res.send(pdfBuffer);
});

API Reference

The SorobanGenerator class provides:

  • generate(config) - Returns { pdf: string, count: number, numbers: number[] }
  • generateBuffer(config) - Returns PDF as Node.js Buffer
  • initialize() - Start persistent Python process for better performance
  • close() - Clean up Python process

All methods use clean TypeScript interfaces with proper types - no shell command building required!

REST API Server

For web services and remote generation:

Start the API Server

# Install FastAPI dependencies
pip3 install fastapi uvicorn

# Start the development server
python3 src/api.py
# or
uvicorn src.api:app --reload --host 0.0.0.0 --port 8000

API Endpoints

# Generate flashcards via POST
curl -X POST "http://localhost:8000/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "range": "0-99",
    "format": "web",
    "color_scheme": "place-value",
    "cards_per_page": 6
  }'

# Health check
curl http://localhost:8000/health

# OpenAPI documentation available at:
# http://localhost:8000/docs (Swagger UI)
# http://localhost:8000/redoc (ReDoc)

API Features

  • 🔄 All formats supported: PDF, PNG, SVG, and interactive web HTML
  • 📊 JSON responses: Base64-encoded files with metadata
  • 🛡️ CORS enabled: Ready for web app integration
  • 📚 Auto documentation: OpenAPI/Swagger specs included
  • ⚡ High performance: Optimized for production workloads

Development

📦 NPM Package Publishing

The @soroban/abacus-react package is automatically published to both npm and GitHub Packages using semantic versioning. To trigger a release:

# For new features (minor version bump)
git commit -m "feat(abacus-react): add new bead animation system"

# For bug fixes (patch version bump)
git commit -m "fix(abacus-react): resolve gesture detection issue"

# For breaking changes (major version bump)
git commit -m "feat(abacus-react)!: change callback signature"

Important: Use the (abacus-react) scope in commit messages to trigger package releases. Regular commits without this scope only affect the monorepo versioning.

📖 Full details: See CONTRIBUTING.md for complete workflow documentation.

Updating Example Images

If you make changes that affect the visual output, please update the example images:

# Regenerate all example images
make examples

# Or use the update script
./scripts/update-examples.sh

# Verify examples are up to date (CI will also check this)
make verify-examples

The CI pipeline will automatically verify that example images are up to date with the code.

Running Tests

The project includes comprehensive test coverage for all functionality:

# Run all tests
python3 -m pytest tests/ -v

# Test specific functionality
python3 -m pytest tests/test_quiz_functionality.py -v  # Interactive quiz features
python3 -m pytest tests/test_web_generation.py -v     # Web format generation
python3 -m pytest tests/test_generation.py -v         # Core generation logic
python3 -m pytest tests/test_config.py -v             # Configuration parsing
python3 -m pytest tests/test_visual.py -v             # Visual output validation

# Quick test build
make test

# Generate all samples
make samples

# Full CI verification (ensures examples are up to date)
make verify-examples

Test Coverage

  • 🧠 Quiz Functionality: Interactive quiz modes, scoring algorithms, progress tracking
  • 🎯 Sorting Challenges: Drag-and-drop mechanics, gap-filling logic, user interactions
  • 🌐 Web Generation: HTML output, CSS styling, JavaScript functionality
  • 📄 PDF Generation: Vector rendering, duplex alignment, cutting guides
  • 🖼️ Image Output: PNG/SVG generation, transparency, resolution scaling
  • ⚙️ Configuration: YAML/JSON parsing, validation, command-line interface
  • 🎨 Visual Output: Color schemes, bead shapes, layout consistency

License

MIT License - see LICENSE file for details.

This project uses DejaVu Sans font (included), which is released under a free license.

📚 Additional Documentation

Web Application

Location: apps/web/ Documentation: apps/web/README.md

The main Next.js web application containing tutorials, practice sessions, arcade games, and worksheet generation.

Arcade Game System

Location: apps/web/src/arcade-games/ Overview: apps/web/src/arcade-games/README.md

Modular, plugin-based architecture for building multiplayer arcade games with real-time synchronization.

Available Games:

  • Know Your World - Geography quiz with precision controls for tiny regions (Precision Controls Docs)
  • Number Guesser - Hot/cold guessing game
  • Memory Quiz - Pattern matching challenge
  • Matching Pairs - Memory card game

Key Documentation:

Worksheet Generator

Location: apps/web/src/app/create/worksheets/ Overview: apps/web/src/app/create/worksheets/README.md

Create customizable math worksheets with progressive difficulty, problem space validation, and Typst-powered PDF generation.

Key Documentation:

Abacus React Component

Package: @soroban/abacus-react Documentation: packages/abacus-react/README.md Storybook: Interactive Examples

React component library for rendering interactive and static abacus visualizations.

Decomposition Display

Location: apps/web/src/components/decomposition/ Documentation: apps/web/src/components/decomposition/README.md

Interactive mathematical decomposition visualization showing step-by-step soroban operations. Features hoverable terms with pedagogical explanations, grouped operations, and bidirectional abacus coordination.

Key Features:

  • Interactive Terms - Hover to see why each operation is performed
  • Pedagogical Grouping - Related operations (e.g., "+10 -3" for adding 7) grouped visually
  • Step Tracking - Integrates with tutorial and practice step progression
  • Abacus Coordination - Bidirectional highlighting between decomposition and abacus

Daily Practice System

Location: apps/web/docs/DAILY_PRACTICE_SYSTEM.md Entry Point: /practice route in the web app

Structured curriculum-based practice system following traditional Japanese soroban teaching methodology.

Key Features:

  • Student Progress Tracking - Per-skill mastery levels (learning → practicing → mastered)
  • Session Planning - Adaptive problem selection based on student history
  • Teacher Controls - Real-time session health monitoring and mid-session adjustments
  • Worksheet Integration - Generate worksheets based on student's current level

🚀 Active Development Projects

Speed Complement Race Port (In Progress)

Status: Planning Complete, Ready to Implement Plan Document: apps/web/COMPLEMENT_RACE_PORT_PLAN.md Source: packages/core/src/web_generator.py (lines 10956-15113) Target: apps/web/src/app/games/complement-race/

A comprehensive port of the sophisticated Speed Complement Race game from standalone HTML to Next.js. Features 3 game modes, 2 AI personalities with 82 unique commentary messages, adaptive difficulty, and multiple visualization systems.