@balancy/bridge

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

Install Dependencies

cd packages/bridge
npm install

Production Build

npm run build

Outputs minified bundle to dist/balancy-webview-bridge.js

Development Build

npm run build:dev

Outputs bundle with inline source maps for debugging

Watch Mode

npm run watch

Automatically rebuilds on file changes

Key Improvements

• Modular Architecture: Code is organized into logical modules by domain
• Type Safety: Full TypeScript typing with strict mode enabled
• Better Minification: 50% size reduction (64KB → 32KB)
  • JavaScript minification via esbuild
  • CSS minification in post-processing
• Single File Bundle: Combined bridge + styles into one file (no more dual injection)
• Auto-copy to SDK: Build automatically updates the core package file
• Maintainability: Easier to navigate and modify specific functionality
• 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:

• 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
• Original files (now replaced):
  • packages/core/src/webview/resources/balancy-webview-bridge.js (40KB)
  • packages/core/src/webview/resources/balancy-webview-styles.js (24KB)
• The new bundle (31.91KB) automatically replaces the old bridge file on build
• You can now remove the styles file injection - everything is in one file
• 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