/// Idiomatic Dart surface over the Nim library.
///
/// Callers never see a Pointer, and never own Nim memory: every string that
/// crosses the boundary is copied into Dart and the Nim allocation is released
/// before the call returns.
///
/// Two backends implement the same signatures — `dart:ffi` against the native
/// shared library, and `dart:js_interop` against the emscripten build — and
/// the conditional import below picks one at compile time. Callers see no
/// difference beyond [supportsIsolateParallelism].
library nimflutter_ffi;

import 'dart:typed_data';

import 'src/backend_native.dart'
    if (dart.library.js_interop) 'src/backend_web.dart' as backend;
import 'src/fractal_view.dart';

export 'src/fractal_view.dart' show FractalView;

/// Which bridge this build is using, for display. 'dart:ffi' or 'wasm'.
const String backendName = backend.backendName;

/// Whether bands can genuinely run at the same time.
///
/// True on native (isolates) and on web (Web Workers, one wasm instance
/// each). False only if the web build is served without nimflutter_pool.js,
/// in which case the split still produces identical pixels, sequentially.
bool get supportsIsolateParallelism => backend.supportsIsolateParallelism;

/// What one unit of parallelism is called here — 'isolate' or 'worker'.
/// Purely for display.
String get parallelUnitName => backend.parallelUnitName;

/// Whether the bridge is ready to take calls.
bool get isInitialized => backend.isInitialized;

/// Prepares the bridge, and the only form that works on every backend.
///
/// Native initialisation is synchronous, but loading a wasm module is not, so
/// the async form is the common denominator. Await this once at startup.
Future<void> initialize() => backend.initialize();

/// Synchronous initialisation. Native-only: on web this throws unless
/// [initialize] has already completed, because the module cannot be loaded
/// synchronously.
void ensureInitialized() => backend.ensureInitialized();

/// Adds two integers in Nim. The trivial case, useful as a liveness check.
int add(int a, int b) => backend.add(a, b);

/// Round-trips a string through Nim.
///
/// Nim allocates the result on the shared heap; this copies it into a Dart
/// [String] and frees the Nim allocation before returning, so there is nothing
/// for the caller to release.
String greet(String name) => backend.greet(name);

/// Runs [greet] off the calling isolate where the backend supports it.
Future<String> greetAsync(String name) => backend.greetAsync(name);

/// Renders rows [y0, y1) of [view] into a fresh RGBA byte buffer.
///
/// The buffer is allocated on the Dart side and filled in place by Nim, so no
/// Nim memory is created and nothing needs freeing.
Uint8List renderBand(FractalView view, int y0, int y1) =>
    backend.renderBand(view, y0, y1);

/// Renders the whole of [view] on the calling isolate.
Uint8List render(FractalView view) => renderBand(view, 0, view.height);

/// Renders [view] as [tiles] horizontal bands.
///
/// Bands are independent by construction — each call writes only its own rows
/// — so this is real parallelism: isolates on native, Web Workers on web,
/// each with its own wasm instance.
Future<Uint8List> renderParallel(FractalView view, {int tiles = 4}) =>
    backend.renderParallel(view, tiles);