npm package: @balancy/bridge
Description: Balancy WebView Bridge - Unity-like component system for HTML/JavaScript
Author: Balancy Team
Latest version: 1.4.5

# 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
```bash
cd packages/bridge
npm install
```

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

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

### Watch Mode
```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
  - Auto-copy to Unity plugin (`plugin_cpp_unity`) on production builds
  - Watch mode skips auto-copy (for development)
  - Development builds skip CSS minification

## Build Copy Targets

The build script (`scripts/build.js`) copies the output to two locations:

1. **Core package**: `packages/core/src/webview/resources/balancy-webview-bridge.js`
2. **Unity plugin**: `plugin_cpp_unity/WebView/Resources/balancy-webview-bridge.txt`

The Unity path is relative — it expects `plugin_cpp_unity` to be cloned as a sibling of `plugin_cpp_typescript`:

```
Projects/
  plugin_cpp_typescript/   <-- this repo
  plugin_cpp_unity/        <-- Unity plugin repo (sibling)
```

The Unity copy silently skips if the directory doesn't exist (wrapped in try/catch). Copying is also skipped in watch mode.