@jorvel/runtime

type NavigateDetail = {
  to: string;                     // pathname + optional ?search and #hash
  mode?: 'push' | 'replace';      // default 'push'
  state?: unknown;                // stored via history.{push,replace}State
};

type RouterOptions = {
  basePath?: string;              // ignore paths outside this prefix
  listenToNavigateEvents?: boolean; // default true
};

type MiddlewareDecision =
  | { type: 'next'; headers?: Record<string, string> }
  | { type: 'redirect'; to: string; status: 301|302|303|307|308 }
  | { type: 'rewrite'; to: string }
  | { type: 'respond'; response: Response };

type Middleware = (ctx: {
  pathname: string;
  searchParams: URLSearchParams;
  url?: URL;
  request?: Request;
  state: Record<string, unknown>;
}) => MiddlewareDecision | void | Promise<MiddlewareDecision | void>;

defineMiddleware(fn: Middleware): Middleware;
next(headers?): MiddlewareDecision;
redirect(to, status = 307): MiddlewareDecision;
rewrite(to): MiddlewareDecision;
respond(response): MiddlewareDecision;

// matcher: '*' = one segment, '**' = any depth; first terminal decision wins
runMiddleware(
  chain: Array<Middleware | { matcher?: string | string[]; handler: Middleware }>,
  init: { pathname: string; searchParams?; url?; request?; state? },
): Promise<MiddlewareDecision>;

// reads use defineLoader / useLoaderData from @jorvel/ssr; actions are the write side
defineAction<I, O>(fn: (input: I, ctx?: { request?; signal? }) => O | Promise<O>): Action<I, O>;

// pending/error/data state machine; concurrent submits are last-wins
useAction<I, O>(action): { data: O | null; error: unknown; pending: boolean; submit(i: I): Promise<O>; reset(): void };

// binds a FormData action to <form onSubmit>; progressive-enhancement friendly
useFormAction<O>(action): { onSubmit(e); submit(fd: FormData): Promise<O>; data; error; pending; reset };

type Validator<T> = { parse(input: unknown): T; safeParse?(input: unknown): { success: true; data: T } | { success: false; error: unknown } };

createRoute<TParams, TSearch>({
  path: string;                   // '/users/:id'
  params?: Validator<TParams>;
  search?: Validator<TSearch>;
}): TypedRoute<TParams, TSearch>;

defineRoutes<T extends Record<string, TypedRoute<any, any>>>(map: T): T;

type GuardResult = boolean | { redirect: string };
type RouteGuard = (ctx: { pathname: string; params: Record<string, string> }) => GuardResult | Promise<GuardResult>;

runGuards(resolved, pathname, globalGuards?: RouteGuard[]): Promise<GuardResult>;

createAuthGuard({
  isAuthenticated: () => boolean | Promise<boolean>;
  loginPath?: string;             // default '/login'
  captureReturnTo?: boolean;      // default true — appends ?next=…
}): RouteGuard;

createRoleGuard({
  hasRole: (role: string) => boolean;
  roles: string[];                // any-of
  fallbackPath?: string;
}): RouteGuard;

preloadRemotes(
  remotes: Array<{ name: string; entryUrl: string; integrity?: string }>,
  opts?: {
    concurrency?: number;   // default 3
    idle?: boolean;         // default true — wraps each load in requestIdleCallback
    idleBudgetMs?: number;  // default 8
    onResult?: (r: { remote: string; ok: boolean; durationMs: number; error?: unknown }) => void;
  },
): Promise<void>;

registerJorvelServiceWorker(opts?: {
  url?: string;                   // default '/jorvel-sw.js'
  scope?: string;                 // default '/'
  autoActivate?: boolean;         // post SKIP_WAITING on update
  onUpdateReady?: () => void;
  onActivated?: () => void;
}): Promise<ServiceWorkerRegistration | null>;

unregisterJorvelServiceWorker(): Promise<boolean>;

// Inline source — useful for build-time injection
declare const JORVEL_SERVICE_WORKER_SOURCE: string;

<ShadowRemote
  mode?: 'open' | 'closed';       // default 'open'
  css?: string;                   // inlined into <style>
  stylesheets?: string[];         // resolved as <link rel="stylesheet">
>{children}</ShadowRemote>

scopeCss(css: string, scopePrefix: string): string;

<Island
  strategy?: 'load' | 'idle' | 'visible' | 'media' | 'interaction';
  media?: string;                 // required when strategy === 'media'
  load: () => Promise<{ default: ComponentType<any> }>;
  fallback?: ReactNode;
  rootMargin?: string;            // IntersectionObserver fine-tuning
/>

clientBoundary<T>(component: T): T;     // marker for future tooling

loadRemoteEntry({
  name: string;
  entryUrl: string;
  integrity?: string;             // SRI hash
}, opts?: {
  allowedOrigins?: string[];      // verified before fetch
  requireIntegrity?: boolean;     // fail closed when no SRI hash is present
  crossOrigin?: 'anonymous' | 'use-credentials' | 'none';
}): Promise<void>;

loadRemoteModule<T = unknown>(
  name: string,
  exposedKey: string,             // './App'
  opts?: { allowedOrigins?: string[]; integrity?: string },
): Promise<T>;

initRemoteContainer(name: string): Promise<void>;

getRemoteRegistry(opts?: {
  allowedOrigins?: string[];
  fetcher?: typeof fetch;
}): RemoteRegistry;

class RemoteRegistry {
  register(d: RemoteDescriptor): void;
  unregister(name: string): void;
  get(name: string): RemoteDescriptor | undefined;
  list(): RemoteDescriptor[];
  load(manifestUrl: string): Promise<void>;
}

checkVersions({
  host: { name: string; version: string };
  remote: { name: string; version: string };
  singletons?: Record<string, string>;
}): Array<{ pkg: string; expected: string; actual: string }>;

createHealthHandler(opts: {
  name: string;
  version: string;
  build?: string;
  shared?: Record<string, string>;
  probes?: Record<string, () => Promise<{ ok: boolean; detail?: string }>>;
}): (req: Request) => Promise<{ status: number; body: HealthBody }>;

fetchHealth(url: string, opts?: { timeoutMs?: number }): Promise<HealthBody>;

useRemoteData<T>(opts: {
  key: string | unknown[];
  fetcher: (signal: AbortSignal) => Promise<T>;
  ttl?: number;                       // ms, default 0 (no cache)
  initialData?: T;                    // from hydration
}): {
  data: T | undefined;
  error: unknown | undefined;
  loading: boolean;
  refresh(): Promise<void>;
};

// tag a read: useRemoteData({ key, fetcher, tags: ['posts', 'post:42'] })
revalidateTag(tag: string): void;          // purge every entry with this tag + signal re-render
revalidatePath(path: string): void;        // sugar: revalidateTag(path)
invalidateRemoteData(key: string): void;   // purge one key
clearRemoteDataCache(): void;              // purge everything
prefetchRemoteData<T>(key, fetcher, ttl?, tags?): Promise<T>;
useRevalidationVersion(): number;          // subscribe a component to revalidation (re-renders on purge)

class QueryClient {
  constructor(opts?: { staleTime?: number; now?: () => number });
  fetchQuery<T>(key, queryFn): Promise<T>;   // dedupes in-flight
  setQueryData<T>(key, updater): void;        // optimistic / hydration
  invalidate(prefix | (key) => boolean): void;
  isStale(key, staleTime?): boolean;
  getEntry<T>(key); clear();
}
QueryClientProvider({ client?, children }); useQueryClient(): QueryClient;

useQuery<T>({ queryKey, queryFn, staleTime?, enabled? }):
  { data; error; status; isLoading; isFetching; isStale; refetch };

useMutation<I, O>({ mutationFn, onSuccess?, onError? }):
  { mutate; mutateAsync; data; error; status; isPending; reset };

// React-18-compatible; same shape as React 19's built-in
useOptimistic<State, Action = State>(
  state: State,
  updateFn: (current: State, optimisticValue: Action) => State,
): [optimisticState: State, addOptimistic: (action: Action) => void];

createWeightedRemote(opts: {
  candidates: Array<{ entryUrl: string; weight: number; healthUrl?: string }>;
  probeIntervalMs?: number;       // default 30_000
  failoverOnError?: boolean;      // default true
}): { resolve(): Promise<string>; dispose(): void };

createBlueGreen(opts: {
  blue:  { entryUrl: string; version: string };
  green: { entryUrl: string; version: string };
  active?: 'blue' | 'green';
}): BlueGreenController;

interface BlueGreenController {
  active: 'blue' | 'green';
  swap(): void;
  resolve(): { entryUrl: string; version: string };
  subscribe(listener: (which: 'blue' | 'green') => void): () => void;
}

interface FeatureFlagProvider {
  getBool(key: string, fallback?: boolean): boolean;
  getString(key: string, fallback?: string): string;
  getNumber(key: string, fallback?: number): number;
  subscribe(listener: () => void): () => void;
}

setFeatureFlagProvider(provider: FeatureFlagProvider): void;
useFeatureFlag(key: string, fallback?: boolean): boolean;
useFeatureFlags<T extends Record<string, boolean>>(keys: T): T;

withRetry<T>(fn: () => Promise<T>, opts?: {
  attempts?: number;              // default 3
  baseDelayMs?: number;           // default 200
  maxDelayMs?: number;            // default 5_000
  jitter?: number;                // 0..1, default 0.3
  shouldRetry?: (err: unknown, attempt: number) => boolean;
}): Promise<T>;

createCircuitBreaker(opts: {
  threshold: number;              // failures before opening
  resetMs: number;
}): {
  exec<T>(fn: () => Promise<T>): Promise<T>;
  state: 'closed' | 'open' | 'half';
};

withTimeout<T>(fn: (signal: AbortSignal) => Promise<T>, ms: number): Promise<T>;

buildFontPreloadLink(href: string, opts?: { type?: string; crossorigin?: 'anonymous' | 'use-credentials' }): {
  rel: 'preload'; as: 'font'; href: string; type: string; crossorigin: string;
};

buildFontFaceCss(faces: Array<{
  family: string;
  src: string;
  weight?: number | string;
  style?: 'normal' | 'italic';
  display?: 'auto' | 'block' | 'swap' | 'fallback' | 'optional';
  unicodeRange?: string;
}>): string;

googleFontsUrl(opts: { families: Array<{ family: string; weights: number[] | { italic: boolean; weight: number }[] }> }): string;
googleFontsPreconnectLinks(): Array<{ rel: 'preconnect'; href: string; crossorigin?: 'anonymous' }>;

<Image
  src: string;
  alt: string;
  width: number;
  height: number;
  widths?: number[];
  formats?: Array<'avif' | 'webp' | 'jpg' | 'png'>;
  breakpoints?: Array<{ minWidth: number; size: string }>;
  fetchPriority?: 'high' | 'low' | 'auto';
  loading?: 'lazy' | 'eager';
/>

buildSrcset(template: string, opts: { widths: number[] } | { density: number[] }): string;
buildSizes(opts: { breakpoints: Array<{ minWidth: number; size: string }>; fallback: string }): string;
buildImagePreloadLink(template: string, opts: {
  widths?: number[];
  sizes?: string;
  fetchPriority?: 'high' | 'low' | 'auto';
}): { rel: 'preload'; as: 'image'; imagesrcset: string; imagesizes?: string; fetchpriority?: string };

deprecate(message: string, opts?: { since?: string; replacement?: string }): void;
deprecated<T extends (...args: any[]) => any>(fn: T, message: string): T;