ballistics-engine 0.13.3 → 0.25.0

package/README.md

@@ -1,614 +1,131 @@
-# Ballistics Engine
+# ballistics-engine (WASM)
 
-A high-performance ballistics trajectory calculation engine with comprehensive physics modeling, automatic zeroing, and statistical analysis capabilities.
+WebAssembly build of [`ballistics-engine`](https://github.com/ajokela/ballistics-engine), a
+high-performance ballistics trajectory engine (RK4 integration, wind/Coriolis/spin-drift/Magnus
+effects, custom drag tables, Monte Carlo, and more). This package exposes the same CLI-style
+command surface as the native Rust binary, plus a small object-oriented `Calculator` class, to
+JavaScript/TypeScript.
 
-**Project Website:** [https://ballistics.rs/](https://ballistics.rs/)
+Built with `wasm-pack` and `--no-default-features` — the native crate's default `pdf`/`online`
+features pull in dependencies that don't compile for `wasm32-unknown-unknown`, so the PDF dope-card
+export and the online BC-estimation API are not available from WASM.
 
-## Features
+> This package is built from `pkg/` (the `wasm-pack --target bundler` output) via
+> `scripts/build-npm.sh` in the source repo. The same script also produces a `pkg-web/` build
+> (`--target web`) for use without a bundler — see "Browser without a bundler" below.
 
-- **Full 3D Trajectory Integration** - Six-state ballistic modeling with adaptive RK45 and fixed-step RK4 integration methods
-- **Advanced Drag Models** - Support for G1, G7, and custom drag curves with automatic transonic corrections
-- **Automatic Zeroing** - Calculate sight adjustments and apply zero angles automatically
-- **Unit Conversion** - Seamless switching between Imperial (default) and Metric units
-- **BC Segmentation** - Velocity-dependent ballistic coefficient modeling with automatic estimation
-- **Atmospheric Modeling** - Temperature, pressure, humidity, and altitude effects with ICAO standard atmosphere
-- **Wind Effects** - 3D wind calculations with altitude-dependent wind shear modeling
-- **Monte Carlo Simulations** - Statistical analysis with parameter uncertainties
-- **BC Estimation** - Estimate ballistic coefficients from trajectory data
-- **Advanced Physics**:
-  - **Spin Effects**: Magnus effect, enhanced spin drift with decay modeling
-  - **Earth Effects**: Coriolis effect with latitude-dependent calculations
-  - **Angular Motion**: Gyroscopic precession and nutation physics
-  - **Transonic Analysis**: Pitch damping coefficients and stability warnings
-  - **Trajectory Sampling**: Regular interval data collection for analysis
-  - **Form Factor Corrections**: Bullet-specific drag adjustments
-- **Multiple Output Formats** - JSON, CSV, and formatted tables
-
-## Installation
-
-### From Source
-
-```bash
-git clone https://github.com/ajokela/ballistics-engine.git
-cd ballistics-engine
-cargo build --release
-```
-
-The binary will be at: `target/release/ballistics`
-
-## Quick Start
-
-### Basic Trajectory (Imperial Units - Default)
-
-```bash
-# .308 Winchester, 168gr bullet at 2700 fps
-./ballistics trajectory -v 2700 -b 0.475 -m 168 -d 0.308 --max-range 1000
-
-# With automatic zeroing at 200 yards
-./ballistics trajectory -v 2700 -b 0.475 -m 168 -d 0.308 --auto-zero 200 --max-range 500
-```
-
-### Metric Units
-
-```bash
-# Same bullet in metric units
-./ballistics trajectory --units metric -v 823 -b 0.475 -m 10.9 -d 7.82 --max-range 1000
-```
-
-## Unit Systems
-
-The engine supports two unit systems, selectable with the `--units` flag:
-
-### Imperial (Default)
-- **Velocity**: feet per second (fps)
-- **Mass**: grains
-- **Distance**: yards
-- **Diameter**: inches
-- **Temperature**: Fahrenheit
-- **Pressure**: inHg
-- **Wind**: mph
-
-### Metric
-- **Velocity**: meters per second (m/s)
-- **Mass**: grams
-- **Distance**: meters
-- **Diameter**: millimeters
-- **Temperature**: Celsius
-- **Pressure**: hPa (millibars)
-- **Wind**: m/s
-
-## Commands
-
-### Trajectory Calculation
-
-Calculate ballistic trajectory with environmental conditions:
-
-```bash
-# Imperial units (default)
-./ballistics trajectory \
-  -v 2700          # Velocity (fps)
-  -b 0.475         # Ballistic coefficient
-  -m 168           # Mass (grains)
-  -d 0.308         # Diameter (inches)
-  --drag-model g7  # G7 drag model
-  --angle 0        # Launch angle (degrees)
-  --max-range 1000 # Maximum range (yards)
-  --wind-speed 10  # Wind speed (mph)
-  --wind-direction 90  # Wind from right (degrees)
-  --temperature 59     # Temperature (Fahrenheit)
-  --pressure 29.92    # Pressure (inHg)
-  --humidity 50       # Relative humidity (%)
-  --altitude 0        # Altitude (feet)
-  --full             # Show all trajectory points
-```
-
-#### Auto-Zero Feature
-
-Automatically calculate and apply the zero angle for a specific distance:
-
-```bash
-# Zero at 200 yards and show trajectory to 500 yards
-./ballistics trajectory \
-  -v 2700 -b 0.475 -m 168 -d 0.308 \
-  --auto-zero 200 \  # Automatically zero at 200 yards
-  --max-range 500 \
-  --full
-
-# Custom sight height for auto-zero
-./ballistics trajectory \
-  -v 2700 -b 0.475 -m 168 -d 0.308 \
-  --auto-zero 100 \
-  --sight-height 0.055  # 2.2 inches in yards
-```
-
-#### Advanced BC Modeling
-
-Enable velocity-dependent BC modeling for more accurate long-range predictions:
-
-```bash
-# Enable BC segmentation (velocity-based BC changes)
-./ballistics trajectory \
-  -v 2700 -b 0.475 -m 168 -d 0.308 \
-  --use-bc-segments \
-  --auto-zero 600 \
-  --max-range 1000
-```
-
-#### Advanced Physics - Magnus and Spin Drift
-
-Enable advanced gyroscopic and aerodynamic effects:
-
-```bash
-# Magnus effect and spin drift calculation
-./ballistics trajectory \
-  -v 2700 -b 0.475 -m 168 -d 0.308 \
-  --twist-rate 10      # 1:10" barrel twist
-  --twist-right        # Right-hand twist
-  --enable-magnus      # Enable Magnus effect
-  --enable-spin-drift  # Enable enhanced spin drift
-  --wind-speed 10 \
-  --wind-direction 90 \
-  --max-range 1000
-
-# Coriolis effect for extreme long range
-./ballistics trajectory \
-  -v 3000 -b 0.750 -m 250 -d 0.338 \
-  --enable-coriolis \
-  --latitude 45        # Shooting latitude
-  --shooting-angle 90  # Azimuth (0=N, 90=E)
-  --max-range 2000
-```
-
-### Zero Calculation
-
-Calculate the sight adjustment needed to zero at a specific distance:
-
-```bash
-# Calculate zero for 200 yards
-./ballistics zero \
-  -v 2700 -b 0.475 -m 168 -d 0.308 \
-  --target-distance 200
-
-# With custom sight height (default is 0.05 yards / 1.8 inches)
-./ballistics zero \
-  -v 2700 -b 0.475 -m 168 -d 0.308 \
-  --target-distance 300 \
-  --sight-height 0.055  # 2.2 inches
-
-# Metric example
-./ballistics zero --units metric \
-  -v 823 -b 0.475 -m 10.9 -d 7.82 \
-  --target-distance 200  # 200 meters
-```
-
-Output includes:
-- Zero angle in degrees
-- Adjustment in MOA (Minutes of Angle)
-- Adjustment in mrad (milliradians)
-- Maximum ordinate (highest point of trajectory)
-
-### Monte Carlo Simulation
-
-Run statistical analysis with parameter variations:
-
-```bash
-./ballistics monte-carlo \
-  -v 2700         # Base velocity (fps)
-  -b 0.475        # Base BC
-  -m 168          # Mass (grains)
-  -d 0.308        # Diameter (inches)
-  -n 1000         # Number of simulations
-  --velocity-std 10    # Velocity std dev (fps)
-  --angle-std 0.5     # Angle std dev (degrees)
-  --bc-std 0.01       # BC std dev
-  --wind-std 2        # Wind speed std dev (mph)
-  --target-distance 300  # Target distance for hit probability
-```
-
-### BC Estimation
-
-Estimate ballistic coefficient from observed trajectory data:
+## Install
 
 ```bash
-./ballistics estimate-bc \
-  -v 2700 -m 168 -d 0.308 \
-  --distance1 100 --drop1 0.0   # First data point
-  --distance2 200 --drop2 0.023  # Second data point
+npm install @SCOPE/ballistics-engine
 ```
 
-## Advanced Features
-
-### Integration Methods
+`@SCOPE` is a placeholder — see the source repo's `README.md` ("WASM / npm Package" section) for
+the real published name once one exists.
 
-The engine supports two numerical integration methods:
+## Quick start (bundler: webpack, Vite, Rollup, Parcel)
 
-- **RK45 (Dormand-Prince Adaptive)** - Default method, provides best accuracy with adaptive step sizing
-- **RK4 (Runge-Kutta 4th Order Fixed-Step)** - Available with `--use-rk4-fixed` flag for faster computation
+This package's `main` entry imports its `.wasm` file as a native ES module, which is how
+`wasm-pack --target bundler` output is meant to be consumed. It works out of the box with Vite and
+Rollup (`@rollup/plugin-wasm`), and with webpack once `experiments.asyncWebAssembly` (or
+`experiments.syncWebAssembly`) is enabled — check your bundler's WASM docs if the import fails.
 
-### Wind Shear Modeling
+```js
+import { WasmBallistics } from '@SCOPE/ballistics-engine';
 
-Model altitude-dependent wind variations:
+const calc = new WasmBallistics();
 
-```bash
-./ballistics trajectory -v 2700 -b 0.475 -m 168 -d 0.308 \
-  --wind-speed 10 --wind-direction 90 \
-  --enable-wind-shear \
-  --max-range 1000
+// The command surface mirrors the native CLI (see CLI_USAGE.md in the source repo for the full
+// flag reference): .308 Winchester, 168gr @ 2700 fps, zeroed at 200 yd, table out to 500 yd.
+const table = calc.runCommand(
+  'trajectory -v 2700 -b 0.475 -m 168 -d 0.308 --max-range 500 --auto-zero 200',
+);
+console.log(table);
 ```
 
-### Transonic Stability Analysis
+### Custom drag tables (`loadDragTable`)
 
-Analyze projectile stability through the transonic regime:
+Supply a measured or manufacturer-published Mach:Cd drag curve (Hornady CDM data, a Lapua/Doppler
+deck, or your own) instead of a G1/G7 model + BC. Once loaded it's applied automatically to every
+`trajectory`, `zero`, `lead`, and `monte-carlo` run — no extra flag needed.
 
-```bash
-./ballistics trajectory -v 3000 -b 0.475 -m 168 -d 0.308 \
-  --enable-pitch-damping \
-  --max-range 2000
-```
+```js
+const csv = 'mach,cd\n0.5,0.220\n0.8,0.230\n1.0,0.520\n1.2,0.480\n1.5,0.400\n2.0,0.330\n2.5,0.300\n';
+calc.loadDragTable(new TextEncoder().encode(csv));
+calc.hasDragTable(); // true
 
-Provides warnings about transonic instability and minimum pitch damping coefficients.
-
-### Trajectory Sampling
-
-Collect trajectory data at regular intervals for detailed analysis:
-
-```bash
-./ballistics trajectory -v 2700 -b 0.475 -m 168 -d 0.308 \
-  --sample-trajectory \
-  --sample-interval 25  # Sample every 25 yards
-  --max-range 1000 -o json
+calc.runCommand('trajectory -v 2700 -b 0.475 -m 168 -d 0.308 --max-range 500');
 ```
 
-### Angular Motion Physics
-
-Model precession and nutation of spinning projectiles:
-
-```bash
-./ballistics trajectory -v 2700 -b 0.475 -m 168 -d 0.308 \
-  --twist-rate 10 \
-  --enable-precession \
-  --max-range 1000
-```
+`loadDragTable` takes raw bytes because WASM has no filesystem access — fetch the CSV yourself
+(`fetch()` in the browser, `fs.readFileSync` in Node) and pass the bytes in. The CSV format is
+documented in the source repo's `CLI_USAGE.md` ("Custom Drag Tables"); a matching
+`loadBc5dTable(bytes)` / `hasBc5dTable()` pair exists for BC5D correction tables.
 
-### Complete Advanced Physics Example
+## Browser without a bundler
 
-```bash
-./ballistics trajectory \
-  -v 2850 -b 0.690 -m 230 -d 0.338 \
-  --drag-model g7 \
-  --twist-rate 8.5 --twist-right \
-  --enable-magnus \
-  --enable-coriolis \
-  --enable-spin-drift \
-  --enable-wind-shear \
-  --enable-pitch-damping \
-  --enable-precession \
-  --sample-trajectory \
-  --latitude 38.5 \
-  --shooting-angle 45 \
-  --wind-speed 15 --wind-direction 270 \
-  --altitude 6000 \
-  --max-range 2000
-```
+For a plain `<script type="module">` page (no build step), use the `pkg-web/` build instead —
+produced by the same `scripts/build-npm.sh`, and the same build already deployed at
+[ballistics.sh](https://ballistics.sh). It ships an explicit async `init()` you call once before
+constructing `WasmBallistics`:
 
-## Physics Modeling
-
-The ballistics engine implements comprehensive physics modeling for accurate trajectory prediction:
-
-### Aerodynamic Effects
-- **Drag Modeling** - Multiple drag functions (G1-G8, JBM, custom curves) with transonic flow corrections
-- **Form Factor** - Projectile efficiency corrections based on shape and design
-- **Reynolds Number Effects** - Viscosity and flow regime corrections
-
-### Gyroscopic Effects  
-- **Spin Drift** - Lateral deviation due to gyroscopic and Magnus effects
-- **Precession** - Gyroscopic precession of spinning projectile
-- **Nutation** - Oscillatory motion superimposed on precession
-- **Spin Decay** - Reduction in spin rate over time due to aerodynamic damping
-- **Pitch Damping** - Aerodynamic moments opposing angular motion
-
-### Environmental Effects
-- **Coriolis Effect** - Earth's rotation influence on long-range trajectories
-- **Magnus Effect** - Force from spinning projectile in crossflow
-- **Wind Shear** - Altitude-dependent wind variations
-- **Atmospheric Stratification** - Density and sound speed variations with altitude
-
-### Stability Modeling
-- **Dynamic Stability** - Gyroscopic and aerodynamic stability calculations
-- **Yaw of Repose** - Equilibrium yaw angle in crosswind
-- **Limit Cycle Yaw** - Bounded oscillatory motion analysis
-
-## FFI Layer
-
-The library includes a Foreign Function Interface (FFI) layer for integration with iOS, Android, and other platforms. The FFI provides C-compatible bindings for all major functionality.
-
-<img src="ios.png" alt="iOS Integration Example" width="35%">
-
-### FFI Features
-- **C-Compatible Structures** - All data structures use C-compatible layouts
-- **Safe Memory Management** - Proper handling of memory across language boundaries
-- **iOS/Swift Integration** - Ready for use with Swift through bridging headers
-- **Android/JNI Support** - Compatible with Java Native Interface
-- **Monte Carlo Simulation** - Statistical analysis with parameter variations
-- **Error Handling** - Graceful error propagation across FFI boundary
-
-### Example FFI Usage (C/Swift)
-```c
-// Create input parameters
-FFIBallisticInputs inputs = {
-    .muzzle_velocity = 823.0,        // m/s
-    .ballistic_coefficient = 0.475,
-    .mass = 0.0109,                  // kg
-    .diameter = 0.00782,             // meters
-    .drag_model = 0,                 // G1
-    .sight_height = 0.05,            // meters
-    .temperature = 15.0,             // Celsius
-    .altitude = 0.0
-};
-
-// Calculate trajectory
-FFITrajectoryResult* result = ballistics_calculate_trajectory(&inputs, NULL, NULL, 1000.0, 0.1);
-
-// Use results
-printf("Max range: %.2f meters\n", result->max_range);
-
-// Clean up
-ballistics_free_trajectory_result(result);
-```
+```html
+<script type="module">
+  import init, { WasmBallistics } from './ballistics_engine.js';
 
-### Monte Carlo Simulation via FFI
-```c
-// Set up Monte Carlo parameters
-FFIMonteCarloParams params = {
-    .num_simulations = 1000,
-    .velocity_std_dev = 10.0,       // m/s variation
-    .angle_std_dev = 0.001,         // radian variation (elevation)
-    .bc_std_dev = 0.01,             // BC variation
-    .wind_speed_std_dev = 2.0,      // m/s wind variation
-    .target_distance = 600.0,       // Target at 600m
-    .azimuth_std_dev = 0.001        // radian variation (horizontal)
-};
-
-// Run simulation
-FFIMonteCarloResults* results = ballistics_monte_carlo(&inputs, NULL, &params);
-
-// Use statistical results
-printf("Mean range: %.2f m (σ=%.2f)\n", results->mean_range, results->std_dev_range);
-printf("Hit probability at 600m: %.1f%%\n", results->hit_probability * 100);
-
-// Access individual shots
-for (int i = 0; i < results->num_results; i++) {
-    printf("Shot %d: Range %.2f m, Impact velocity %.2f m/s\n", 
-           i, results->ranges[i], results->impact_velocities[i]);
-}
-
-// Clean up
-ballistics_free_monte_carlo_results(results);
+  await init(); // fetches and instantiates ballistics_engine_bg.wasm relative to this file
+  const calc = new WasmBallistics();
+  console.log(calc.runCommand('trajectory -v 2700 -b 0.475 -m 168 -d 0.308 --max-range 500'));
+</script>
 ```
 
-## Output Formats
+Serve `ballistics_engine.js` and `ballistics_engine_bg.wasm` from the same directory, and make sure
+your host serves `.wasm` with `Content-Type: application/wasm` (all major static hosts and CDNs do
+this by default).
 
-All commands support three output formats via the `-o` flag:
+This `pkg-web/` build is not published to npm as part of this package in the current release —
+it's built locally alongside `pkg/` for direct use or self-hosting. If you need it from npm, either
+vendor the files from `pkg-web/` yourself or publish it as a second package.
 
-- **table** (default) - Formatted ASCII table for terminal display
-- **json** - Complete data in JSON format for programmatic use
-- **csv** - Comma-separated values for spreadsheet analysis
+### Node.js without a bundler
 
-## Practical Examples
+Plain Node `import`/`require` cannot load this package's bundler-target `.wasm` import directly.
+Use the `pkg-web/` build instead, passing the file bytes explicitly (Node's `fetch()` does not
+support `file://` URLs):
 
-### Hunting Zero
+```js
+import { readFileSync } from 'node:fs';
+import init, { WasmBallistics } from './pkg-web/ballistics_engine.js';
 
-Zero a hunting rifle at 200 yards with environmental conditions:
+const wasmBytes = readFileSync(new URL('./pkg-web/ballistics_engine_bg.wasm', import.meta.url));
+await init({ module_or_path: wasmBytes });
 
-```bash
-# Calculate zero angle
-./ballistics zero \
-  -v 2650 -b 0.460 -m 180 -d 0.308 \
-  --target-distance 200
-
-# Verify trajectory with auto-zero
-./ballistics trajectory \
-  -v 2650 -b 0.460 -m 180 -d 0.308 \
-  --auto-zero 200 \
-  --max-range 400 \
-  --wind-speed 15 \
-  --wind-direction 270 \
-  --temperature 32 \
-  --humidity 30 \
-  --altitude 5000 \
-  --full
+const calc = new WasmBallistics();
+console.log(calc.runCommand('trajectory -v 2700 -b 0.475 -m 168 -d 0.308 --max-range 500'));
 ```
 
-### Long Range Shooting
+If you need a CommonJS (`require()`) Node build, generate one yourself:
+`wasm-pack build --target nodejs --no-default-features`.
 
-Analyze trajectory for 1000-yard shot:
+## Caveats
 
-```bash
-./ballistics trajectory \
-  -v 2850 -b 0.690 -m 230 -d 0.338 \
-  --drag-model g7 \
-  --auto-zero 100 \
-  --max-range 1100 \
-  --wind-speed 10 \
-  --wind-direction 45 \
-  --full \
-  -o json > trajectory.json
-```
-
-### Load Development
-
-Compare different loads using Monte Carlo:
-
-```bash
-# Load 1: Higher velocity, more variation
-./ballistics monte-carlo \
-  -v 2750 -b 0.475 -m 168 -d 0.308 \
-  -n 1000 \
-  --velocity-std 15 \
-  --target-distance 600
-
-# Load 2: Lower velocity, more consistent
-./ballistics monte-carlo \
-  -v 2680 -b 0.475 -m 168 -d 0.308 \
-  -n 1000 \
-  --velocity-std 8 \
-  --target-distance 600
-```
-
-## Advanced Features
-
-### BC Segmentation
-
-Velocity-dependent BC modeling accounts for how ballistic coefficient changes as the bullet slows down. Enable with `--use-bc-segments`:
-
-- Automatically estimates BC segments based on bullet characteristics
-- No external data required - uses caliber, weight, and BC
-- Identifies bullet type (Match, Hunting, VLD, etc.) from parameters
-- Applies physics-based BC degradation curves
-
-Example:
-```bash
-./ballistics trajectory -v 2700 -b 0.475 -m 168 -d 0.308 --use-bc-segments --max-range 1000
-```
-
-
-### Advanced Physics Modeling
-
-When enabled, the engine calculates:
-- **Magnus Effect** - Side force from spinning projectiles
-- **Spin Drift** - Lateral drift due to gyroscopic effects
-- **Coriolis Effect** - Earth rotation effects (with latitude input)
-- **Transonic Drag** - Enhanced drag modeling in transonic regime
-- **Reynolds Number Corrections** - Viscous effects at low velocities
-
-## Building from Source
-
-### Requirements
-
-- Rust 1.70 or later
-- Cargo build system
-
-### Build Commands
-
-```bash
-# Debug build
-cargo build
-
-# Release build (optimized)
-cargo build --release
-
-# Run tests
-cargo test
-
-# Build documentation
-cargo doc --open
-```
-
-## Library Usage
-
-Use as a Rust library in your own projects:
-
-```rust
-use ballistics_engine::{
-    BallisticInputs, TrajectorySolver, 
-    WindConditions, AtmosphericConditions
-};
-
-fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let inputs = BallisticInputs {
-        muzzle_velocity: 823.0,  // m/s
-        launch_angle: 0.0,       // radians
-        ballistic_coefficient: 0.475,
-        mass: 0.0109,            // kg
-        diameter: 0.00782,       // meters
-        sight_height: 0.05,      // meters
-        ..Default::default()
-    };
-    
-    let wind = WindConditions {
-        speed: 5.0,              // m/s
-        direction: 1.5708,       // 90 degrees in radians
-        ..Default::default()
-    };
-    
-    let atmosphere = AtmosphericConditions {
-        temperature: 15.0,       // Celsius
-        pressure: 1013.25,       // hPa
-        humidity: 50.0,          // %
-        altitude: 0.0,           // meters
-        ..Default::default()
-    };
-    
-    let solver = TrajectorySolver::new(inputs, wind, atmosphere);
-    let result = solver.solve()?;
-    
-    println!("Max range: {:.2} m", result.max_range);
-    println!("Max height: {:.2} m", result.max_height);
-    println!("Time of flight: {:.3} s", result.time_of_flight);
-    
-    Ok(())
-}
-```
-
-## Performance
-
-Optimized Rust implementation provides:
-- Single trajectory (1000m): ~5ms
-- Monte Carlo (1000 runs): ~500ms  
-- BC estimation: ~50ms
-- Zero calculation: ~10ms
-
-## Common Ballistic Coefficients
-
-| Caliber | Weight | BC (G1) | BC (G7) | Description |
-|---------|--------|---------|---------|-------------|
-| .223    | 55gr   | 0.250   | -       | FMJ |
-| .223    | 77gr   | 0.362   | 0.182   | Match |
-| .308    | 168gr  | 0.475   | 0.224   | Match |
-| .308    | 175gr  | 0.505   | 0.253   | Match |
-| .308    | 180gr  | 0.480   | -       | Hunting |
-| .338    | 300gr  | 0.768   | 0.383   | Match |
-| 6.5mm   | 140gr  | 0.620   | 0.310   | Match |
-| .50     | 750gr  | 1.050   | 0.520   | Match |
-
-## Troubleshooting
-
-### Trajectory hits ground early
-- Check if you're using `--auto-zero` or setting `--angle` manually
-- Default angle is 0° (horizontal), which will hit ground quickly
-- Use `--auto-zero <distance>` to automatically calculate proper angle
-
-### Units confusion
-- Default is Imperial (fps, grains, yards)
-- Use `--units metric` for metric system
-- All inputs must match the selected unit system
-
-### Unexpected BC behavior
-- G1 and G7 models have different BC values for same bullet
-- G7 typically better for boat-tail bullets
-- BC segmentation automatically applied based on bullet type
-
-## Contributing
-
-Contributions are welcome! Please:
-1. Fork the repository
-2. Create a feature branch
-3. Add tests for new features
-4. Run `cargo test` and `cargo fmt`
-5. Submit a pull request
+- **Size**: the `.wasm` binary is roughly 430 KB (about 175 KB gzipped). It is not code-split or
+  lazily loaded — the whole engine loads up front.
+- **Single-threaded**: no SIMD/threads assumptions; no `SharedArrayBuffer` or
+  cross-origin-isolation (COOP/COEP) headers required.
+- **No filesystem/network**: table loaders (`loadDragTable`, `loadBc5dTable`) and any file-based
+  CLI flags (e.g. native `--drag-table <FILE>`) need the host to fetch bytes and hand them in; see
+  `loadDragTable` above.
+- **`pdf`/`online` features are unavailable**: this build excludes them (see above), so
+  PDF dope-card export and the online BC-estimation API are not part of the WASM surface.
+- Full API surface (including the `Calculator` builder class) is documented in the bundled
+  `.d.ts`; the full CLI flag reference `runCommand` accepts is documented in the source repo's
+  `CLI_USAGE.md`.
 
 ## License
 
-This project is licensed under the MIT License - see LICENSE file for details.
-
-## Acknowledgments
-
-- Ballistics physics based on Robert McCoy's "Modern Exterior Ballistics"
-- Drag tables from military ballistics research
-- BC segmentation algorithms from Bryan Litz's research
-- Community contributions and testing
+MIT OR Apache-2.0 — see `LICENSE` and `LICENSE-APACHE` in this package.
 
-## Support
+## Source
 
-For issues, questions, or contributions:
-- GitHub Issues: [github.com/ajokela/ballistics-engine/issues](https://github.com/ajokela/ballistics-engine/issues)
+https://github.com/ajokela/ballistics-engine