import { ComponentType } from 'react';
import { ReactNode } from 'react';

/**
 * Look up a registered island Component by name. Returns undefined if
 * the name isn't registered (typically means the user forgot to import
 * the island file in this bundle).
 */
export declare const getIslandComponent: (name: string) => ComponentType<unknown> | undefined;

/**
 * Client-side runtime: scan the document for `[data-voltro-island]`
 * markers and schedule each for hydration per its strategy. Called by the
 * per-page islands entry, and by `@voltro/web/mount` when an islands page
 * is reached through the full app bundle (SPA navigation). Idempotent —
 * running twice is a no-op (we mark elements as visited).
 */
export declare const hydrateIslandsOnPage: (options?: HydrateIslandsOptions) => void;

export declare interface HydrateIslandsOptions {
    /** Wrap every island root — the per-page islands entry of a page whose
     *  islands use framework hooks passes a `<VoltroRuntimeProvider>` here so
     *  a `useSubscription` island gets a live runtime. Purely presentational
     *  entries pass nothing and never load the client core. */
    readonly wrap?: (children: ReactNode) => ReactNode;
}

export declare type HydrateStrategy = 
/** Hydrate as soon as the client runtime mounts (after main script load). */
'load'
/** Hydrate when the browser is idle (via `requestIdleCallback`, with a
*  setTimeout fallback for browsers that lack it). */
| 'idle'
/** Hydrate when the element scrolls into the viewport (IntersectionObserver). */
| 'visible'
/** Hydrate on the first pointer / keyboard interaction with the element. */
| 'interaction'
/** Never hydrate. Useful for fully-static islands (e.g. SSR-only data
*  display that never changes). */
| 'never'
/** CLIENT-ONLY: the server renders an empty placeholder (never the
*  component — a browser-only lib touching `window` in render would
*  crash the SSR pass), and the client mounts fresh with `createRoot`
*  instead of hydrating. Astro's `client:only`. */
| 'only';

/**
 * Wrap a Component as an island. The returned Component renders the
 * inner content wrapped in a marker `<div data-voltro-island>` that
 * carries the island's name + props + hydrate strategy. The same
 * call also registers the Component under its name so the client
 * runtime can find it when hydrating.
 */
export declare const island: <P extends Record<string, unknown>>(Component: ComponentType<P>, options: IslandOptions) => ComponentType<P>;

export declare interface IslandOptions {
    /** Stable id of this island. Must be unique within an app. The framework
     *  uses it to match the server-rendered marker with the client-side
     *  Component. */
    readonly name: string;
    /** When the client runtime should hydrate this island. Defaults to
     *  `visible` — matches Astro's default and is the best perf/UX balance. */
    readonly hydrate?: HydrateStrategy;
}

export { }


declare global {
    interface Window {
        readonly voltroDiagnostics?: VoltroDiagnosticsControl;
    }
}