import { NativeNodeId } from "./native-protocol.js";
import { MindeesNode } from "@mindees/core";

//#region src/native-app.d.ts
/** The contract a native host drives: render once, dispatch events, and tick frames. */
interface NativeApp {
  /** Mount the app and flush the initial command batch to the host. */
  start(): void;
  /**
   * Invoke a registered handler (a native event fired), then flush the resulting batch.
   * `dispatchEvent(handlerId)` for notify-only events (press/click); `dispatchEvent(handlerId, value)`
   * for value-carrying events (text change) — JS wraps `value` as `{ target: { value } }` so handlers
   * read it via the standard event shape. The host passes the RAW string value (never the object);
   * an absent/null value (no second arg) leaves notify-only behavior unchanged.
   */
  dispatchEvent(handlerId: string, value?: string | null): boolean;
  /**
   * Advance animations by one frame: forward the host's vsync timestamp (ms) to the animation
   * engine, then flush the resulting command batch. The host calls this each vsync while the frame
   * loop is active (see {@link CreateNativeAppOptions}). A no-op when no frame source is installed.
   */
  frameTick(nowMs: number): void;
}
/** Options for {@link createNativeApp}. */
interface CreateNativeAppOptions {
  /**
   * Id of the host's pre-existing root container. Defaults to `"host-root"` — the
   * convention the reference hosts register — so the common case needs no config.
   */
  readonly rootId?: NativeNodeId;
  /**
   * How to deliver a command batch to the host. Defaults to `globalThis.MindeesHost.emit`
   * (what the embedded hosts inject). Override in tests or alternative transports.
   */
  readonly emit?: (json: string) => void;
  /**
   * Expose the app on a global so the host can call `start()`/`dispatchEvent()`/`frameTick()`.
   * `true` (default) → `globalThis.MindeesApp`; a string → that global name; `false` →
   * don't expose (use the returned handle directly, e.g. in Node tests).
   */
  readonly expose?: boolean | string;
  /**
   * Install the reactive scheduler that powers `startTransition`/`deferred`/normal-lane effects.
   * `createNativeApp` owns this scheduler so it can flush the command batch after each microtask
   * drain (otherwise deferred mutations would recompute but never reach the host). Pass `false` to
   * run the pure synchronous lane; to use a fully custom scheduler, pass `false` and call
   * `setReactiveScheduler` yourself (you then own flushing).
   */
  readonly scheduler?: false;
  /**
   * Install the reactive scheduler + the vsync frame source. Default: `true` when the app is
   * exposed AND a host (`globalThis.MindeesHost`) is present — so SSR/Node/tests install nothing
   * and keep the synchronous jump-to-final behavior. Pass `true` to force-wire (e.g. tests driving
   * `frameTick` directly).
   */
  readonly wireEngines?: boolean;
}
/**
 * Wire a root node to a native command host. Returns the {@link NativeApp} handle and
 * (unless `expose: false`) publishes it as `globalThis.MindeesApp` for the host to call.
 */
declare function createNativeApp(root: MindeesNode, options?: CreateNativeAppOptions): NativeApp;
//#endregion
export { CreateNativeAppOptions, NativeApp, createNativeApp };
//# sourceMappingURL=native-app.d.ts.map