How apersongithub/duolingo-unlimited-hearts works
1. What this repository is
- A browser add-on project that patches Duolingo at runtime, with two packaged extension targets:
- extension/stable/chrome
- extension/stable/firefox
- It also ships standalone userscript variants in userscript/ for browsers/environments that run userscripts instead of extensions.
2. Primary product shape
- The core behavior is not a standalone app; it is a web-page interceptor and injector that modifies Duolingo’s client-side behavior as the user browses duolingo.com / duolingo.cn.
- The README explicitly frames it as patching Duolingo assets and behavior, including “unpatched webpack chunk files” served from CloudFront.
3. Main runtime boundaries
- Background context: background.js / background.html manages extension-wide behavior, settings, and likely request interception or update coordination.
- Content-script/page context: content_script.js, page_hook.js, and injection.js bridge from extension context into the Duolingo page.
- UI surfaces: popup.* and options.* provide user controls and configuration.
- Shared patch logic: shared/defaults.js and shared/patches.js centralize defaults and patch definitions used by both browser builds.
4. Injection and patching flow
- The patching path appears to be:
1. User opens Duolingo.
2. Extension loads content script.
3. Content script hooks the page and injects patch code into page scope.
4. Page hook/injection scripts alter page behavior and/or client bundle behavior.
- This separation suggests the code needs both extension privileges and in-page execution rights, which is why there are dedicated hook and injection files.
5. Network-level dependency
- A key architecture point is that the extension depends on Duolingo’s own delivery pipeline:
- duolingo.com / duolingo.cn for the application page
- d35aaqx5ub95lt.cloudfront.net for the JS chunk assets that get modified/overridden
- The README also notes raw.githubusercontent.com is used to fetch extension-version.json, which acts as remote metadata for versioning, patch sync, update log, and banner content.
6. Extension UI and user configuration
- The extension exposes a popup and options page in both browser builds:
- popup.html/css/js
- options.html/css/js
- These are the control surfaces for enabling/disabling patch modes and related settings.
- The only explicitly documented browser storage dependency is storage, used to persist patching mode and settings.
7. Chrome vs Firefox packaging
- The Chrome and Firefox trees are parallel but not identical, indicating browser-specific packaging and manifest differences.
- Both bundles include the same conceptual modules, but Firefox has background.html alongside background.js, which points to a browser-specific background-page/bootstrap pattern.
- The duplicated structure suggests shared logic is manually mirrored rather than generated from one build pipeline in this repo.
8. Userscript distribution
- userscript/ contains separate .user.js builds:
- Duolingo Max.user.js
- Duolingo Super.user.js
- Duolingo Super Immersive.user.js
- Duolingo Unlimited Hearts.user.js
- These are alternative delivery artifacts for environments like Safari + Userscripts on iPhone/iPad, bypassing the browser-extension packaging model.
9. Patch set organization
- The userscripts/patch4.js through patch7.js files under each browser target suggest the patch logic is split into versioned or feature-specific chunks.
- shared/patches.js likely selects and applies these patches, while defaults.js provides baseline configuration.
- This implies the architecture is patch-driven rather than a monolithic script.
10. Ancillary assets and docs
- extension-version.json at repo root is a remote-synced metadata file consumed by the extension.
- extras/ contains non-runtime materials: donation page, patcher notes, and release notes.
- .github/ is mostly release/support workflow and issue templates, not runtime architecture.
11. External services and distribution
- The project is distributed through:
- Mozilla Add-ons for Firefox
- Chrome Web Store historically, but the README says that channel is no longer supported
- GitHub Releases for manual installs
- Greasyfork for userscripts
- Those channels matter because they determine which artifact shape is used, but not the core patching architecture.
12. Diagramming guidance
- The core diagram should show:
- User browser loading Duolingo pages
- Extension/userscript layer intercepting the page
- Background/settings storage as a separate control plane
- Injected page hooks modifying in-page behavior
- Remote metadata fetch from GitHub
- Duolingo and CloudFront as the external content sources being adapted
Main entry points: background.js Background · content_script.js Content script · chrome Chrome build · firefox Firefox build
Components 17
External systems
Duolingo runtime, delivery assets, remote metadata, and browser storage
- Browser · Host browser running the add-on or userscript
- Duolingo app · Duolingo pages the repo patches at runtime
- Chunk assets · Duolingo webpack chunk delivery served from CloudFront
- Version meta · extension-version.json fetched from GitHub raw content
extension-version.json - Storage · Browser storage used for settings and patch mode
Extension runtime
Packaged browser extension targets and their in-page injection flow
- Chrome build · Packaged Chrome extension tree
extension/stable/chrome - Firefox build · Packaged Firefox extension tree
extension/stable/firefox - Background · Extension control plane and coordination entrypoint
extension/stable/chrome/background.js - Content script · Injected bridge between extension context and Duolingo page
extension/stable/chrome/content_script.js - Page hook · Page-context hook used to reach in-page Duolingo code
extension/stable/chrome/page_hook.js - Injection · Script that enters page scope and applies runtime changes
extension/stable/chrome/injection.js - Popup UI · Quick controls for patch state and actions
extension/stable/chrome/popup.html - Options UI · Settings surface for persistent configuration
extension/stable/chrome/options.html - Defaults · Baseline settings shared by browser builds
extension/stable/chrome/shared/defaults.js - Patch logic · Central patch definitions and selection logic
extension/stable/chrome/shared/patches.js - Patch chunks · Versioned/feature patch fragments used by the injected runtime
extension/stable/chrome/userscripts
Userscript delivery
Standalone .user.js artifacts for userscript-capable browsers
- Userscripts · Standalone .user.js builds for userscript environments
userscript
Connections 21
- Browser → Chrome build: loads · Browser loads the Chrome extension package
- Browser → Firefox build: loads · Browser loads the Firefox extension package
- Chrome build → Background: boots · Chrome package starts its background logic
- Firefox build → Background: boots · Firefox package mirrors the same background role
- Chrome build → Content script: registers · Extension installs the page bridge content script
- Firefox build → Content script: registers · Firefox build installs the page bridge content script
- Content script → Page hook: injects · Content script enters page context through a hook
- Page hook → Injection: passes through · Hook hands execution to the injected patch runtime
- Injection → Duolingo app: patches · Injected code changes Duolingo page behavior at runtime
- Duolingo app → Chunk assets: loads assets · Duolingo app consumes chunk files from CloudFront
- Background → Defaults: reads · Background logic uses shared baseline settings
- Background → Patch logic: applies · Background coordinates patch definitions
- Background → Storage: persists · Settings and patch mode are stored in browser storage
- Popup UI → Background: controls · Popup provides quick actions for the background plane
- Options UI → Background: configures · Options page writes persistent settings via background
- Defaults → Patch logic: feeds · Defaults seed patch selection and behavior
- Patch logic → Patch chunks: selects · Patch registry resolves the patch chunk set
- Userscripts → Patch chunks: bundles · Standalone userscripts package the same patch-oriented logic
- Version meta → Background: updates · Remote metadata informs versioning and patch sync
- Browser → Userscripts: runs · Userscript-capable browsers execute the standalone artifacts
- Content script → Background: messaging · Content script exchanges state and commands with background