Balancy WebView Bridge - TypeScript Package

This package contains the TypeScript implementation of the Balancy WebView Bridge, which has been migrated from a single JavaScript file to a modular TypeScript codebase.

Phase 1 Complete ✅

The initial setup and migration have been completed. Both the bridge file and styles file have been merged into a single TypeScript package:

- Original files: 40KB (bridge) + 24KB (styles) = 64KB total
- New build: 31.91KB minified (50% size reduction)
- Single injection: Instead of injecting 2 files, now you only inject 1
- Auto-copy: Build automatically copies to core package for SDK inclusion

Project Structure

``
packages/bridge/
├── dist/ # Build output
│ └── balancy-webview-bridge.js # Minified bundle
├── src/
│ ├── index.ts # Main entry point
│ ├── types.ts # Type definitions
│ ├── constants.ts # Enums and constants
│ ├── messaging/ # Request/response handling
│ │ ├── BatchManager.ts
│ │ ├── messageHandler.ts
│ │ └── requestHandler.ts
│ ├── cache/ # Caching systems
│ │ ├── ImageCache.ts
│ │ └── LocalizationCache.ts
│ ├── api/ # API method groups
│ │ ├── profile.ts
│ │ ├── offers.ts
│ │ ├── tasks.ts
│ │ ├── inventory.ts
│ │ ├── battlepass.ts
│ │ └── events.ts
│ ├── ui/ # UI preparation methods
│ │ ├── localization.ts
│ │ ├── images.ts
│ │ ├── fonts.ts
│ │ ├── buttons.ts
│ │ └── dynamicText.ts
│ ├── styles/ # CSS & performance optimizations
│ │ └── gameUI.ts # Game UI styles & behaviors
│ ├── utils/ # Utility functions
│ │ ├── formatting.ts
│ │ ├── templates.ts
│ │ └── dom.ts
│ ├── components/ # Component system (Phase 2+)
│ ├── serialization/ # Serialization system (Phase 3+)
│ ├── managers/ # Managers (Phase 4+)
│ └── initialization.ts # Initialization flow
├── scripts/
│ └── build.js # esbuild configuration
├── package.json
├── tsconfig.json
└── README.md
`

Build Scripts

$3


`bash
cd packages/bridge
npm install
`

$3

`bash
npm run build
`
Outputs minified bundle to dist/balancy-webview-bridge.js

$3

`bash
npm run build:dev
`
Outputs bundle with inline source maps for debugging

$3

`bash
npm run watch
`
Automatically rebuilds on file changes

Key Improvements

1. Modular Architecture: Code is organized into logical modules by domain
2. Type Safety: Full TypeScript typing with strict mode enabled
3. Better Minification: 50% size reduction (64KB → 32KB)
- JavaScript minification via esbuild
- CSS minification in post-processing
4. Single File Bundle: Combined bridge + styles into one file (no more dual injection)
5. Auto-copy to SDK: Build automatically updates the core package file
6. Maintainability: Easier to navigate and modify specific functionality
7. Build Pipeline: Fast, modern build system with esbuild

Current Status

✅ Phase 1 Complete: TypeScript setup and migration
- All existing functionality preserved (bridge + styles)
- Build pipeline operational with CSS minification
- Code organized into modules
- Single unified bundle (31.91KB - 50% reduction)
- Auto-copy to core package on build
- Ready for Phase 2 implementation

Next Steps

Phase 2 will implement the Unity-like component system:
- ElementBehaviour base class
- ElementObject wrapper
- Script registry
- GUID management
- And more...

Testing

Before proceeding to Phase 2, test the current build:

1. The bundle is automatically built to:
- Build output: packages/bridge/dist/balancy-webview-bridge.js
- Auto-copied to: packages/core/src/webview/resources/balancy-webview-bridge.js
2. Original files (now replaced):
- ~~packages/core/src/webview/resources/balancy-webview-bridge.js~~ (40KB)
- ~~packages/core/src/webview/resources/balancy-webview-styles.js~~ (24KB)
3. The new bundle (31.91KB) automatically replaces the old bridge file on build
4. You can now remove the styles file injection - everything is in one file
5. Compare functionality to ensure identical behavior

Technical Notes

- Target: ES2020
- Module Format: IIFE (for browser global access)
- Global: window.balancy`
- Minifier: esbuild (JavaScript) + custom CSS minifier
- TypeScript: Strict mode enabled
- Build Features:
- Automatic CSS minification in post-processing
- Auto-copy to core package on production builds
- Watch mode skips auto-copy (for development)
- Development builds skip CSS minification