import { ComponentType } from 'react';
import { Context } from 'react';
import { ImgHTMLAttributes } from 'react';
import { MouseEvent as MouseEvent_2 } from 'react';
import { ProcedureInput } from '@voltro/client';
import { ProcedureOutput } from '@voltro/client';
import { ProcedureTypeMap } from '@voltro/client';
import { ReactElement } from 'react';
import { ReactNode } from 'react';
import { Ref } from 'react';
import { ResolvableHeaders } from '@voltro/client';
import { Rpc } from '@effect/rpc';
import { RpcGroup } from '@effect/rpc';

/** Decision outcome for a document-level anchor click. */
export declare type AnchorNavigationDecision = {
    readonly kind: 'spa';
    readonly to: string;
} | {
    readonly kind: 'native';
};

/**
 * Map of api name → resolved typed rpc client. Installed by the
 * framework's mount() bootstrap. Consumers read it via useAppClient().
 */
export declare type AppClients = ReadonlyMap<string, unknown>;

export declare const AppClientsContext: Context<AppClients | null>;

/** Render a deferred loader value behind a streamed `<Suspense>` boundary. */
export declare const Await: <T>({ value, fallback, children, errorFallback }: AwaitProps<T>) => ReactNode;

export declare interface AwaitProps<T> {
    /** A deferred field off `useLoaderData()`. */
    readonly value: Promise<T>;
    /** Rendered until the value arrives. This is what the STREAMED SHELL
     *  contains, so keep it cheap and layout-stable. */
    readonly fallback: ReactNode;
    /** Rendered with the resolved value. */
    readonly children: (value: T) => ReactNode;
    /** Rendered if the deferred promise REJECTS. Without it a rejection
     *  propagates to the route's `error.tsx` and takes the whole page with it —
     *  usually the wrong trade for a subtree that was deferred precisely
     *  because it is optional. */
    readonly errorFallback?: ReactNode;
}

/** A navigation the blocker is holding back. `retry()` proceeds with the
 *  original navigation; `reset()` cancels it and clears the block. */
export declare interface BlockedNavigation {
    /** The `to` argument of the held-back `navigate` call. */
    readonly to: string;
    /** The options of the held-back call (e.g. `{ replace: true }`). */
    readonly opts?: NavigateOptions;
    /** Proceed with the blocked navigation (bypasses the guard once). */
    readonly retry: () => void;
    /** Cancel the blocked navigation and return to the idle state. */
    readonly reset: () => void;
}

/** A registered navigation guard. Returns `true` to BLOCK the pending
 *  navigation. `to`/`opts` describe where the user is trying to go. */
export declare type BlockerFn = (next: {
    readonly to: string;
    readonly opts?: NavigateOptions;
}) => boolean;

/** The state a `useBlocker` returns. `blocked` is `false` until a navigation
 *  is held back; when true, `retry()`/`reset()` proceed or cancel it. */
export declare type BlockerState = {
    readonly blocked: false;
} | {
    readonly blocked: true;
    /** Where the user is trying to go. */
    readonly to: string;
    /** Proceed with the held-back navigation. */
    readonly retry: () => void;
    /** Cancel the held-back navigation. */
    readonly reset: () => void;
};

/** A breadcrumb entry — the last one is rendered as the current page. */
export declare interface BlogBreadcrumb {
    readonly label: string;
    readonly href?: string;
}

/**
 * The blog/changelog content shell. Centered max-width container with a
 * sticky header (brand + top nav), optional breadcrumbs, and an optional
 * footer.
 */
export declare const BlogLayout: (props: BlogLayoutProps) => ReactNode;

export declare interface BlogLayoutProps {
    readonly brand: ReactNode;
    readonly topNav: ReadonlyArray<BlogNavItem>;
    readonly children: ReactNode;
    /** Active path for top-nav + breadcrumb highlighting. */
    readonly pathname?: string;
    /** Optional node pinned to the right of the header, after the nav — e.g. a
     *  language switcher or action buttons. */
    readonly headerRight?: ReactNode;
    /** Router link component (e.g. `PlainLink` from @voltro/web). */
    readonly Link?: ComponentType<BlogLinkProps>;
    readonly footer?: ReactNode;
    readonly breadcrumbs?: ReadonlyArray<BlogBreadcrumb>;
}

/** Minimal shape a link component must satisfy (matches PlainLinkProps). */
export declare interface BlogLinkProps {
    readonly to: string;
    readonly children: ReactNode;
    readonly className?: string;
}

/** A top-nav entry. */
export declare interface BlogNavItem {
    readonly label: string;
    readonly href: string;
}

export declare interface BrowserConsoleBridge {
    /** Restore `console.*`, flush pending entries one last time. */
    readonly dispose: () => void;
}

export declare interface BrowserConsoleBridgeOptions {
    /** URL the CLI mounts `/_voltro/inspect/clientLog` on. Pass the
     *  same origin the page is loaded from in the common case
     *  (`window.location.origin`); the CLI's webDev middleware accepts
     *  it without CORS preflight. */
    readonly baseUrl: string;
    /** Voltro app name (the `name:` from `app.config.ts`). Carried in
     *  every batch so multi-app dev setups can attribute log lines. */
    readonly appName: string;
    /** Override flush interval (default 400ms). Mainly for tests. */
    readonly flushAfterMs?: number;
}

/** Absolute canonical URL for a page. Relative paths are also valid in a
 *  `<link rel="canonical">` (crawlers resolve them against the document base),
 *  but an absolute one is unambiguous across environments — pass the production
 *  `siteUrl` and the page's root-relative `path`. */
export declare const canonicalUrl: (siteUrl: string, path: string) => string;

/**
 * Structured result of running a route's loaders: the page (leaf) loader's
 * data plus each chain segment's loader data, keyed by segment index.
 */
export declare interface ChainLoaderData {
    readonly page: unknown;
    readonly segments: Readonly<Record<number, unknown>>;
}

declare interface CompiledRoute extends PageDescriptor {
    readonly regex: RegExp;
    /** Names of capture groups, in match order. Catch-all params capture
     *  a `/`-joined string of the remaining path segments. */
    readonly paramNames: ReadonlyArray<string>;
    /** Sort priority — lower wins. Static segments rank above dynamic,
     *  dynamic above catch-all. Ensures `/users/me` beats `/users/[id]` and
     *  both beat `/users/[...rest]`. */
    readonly priority: number;
}

export declare const compileRoute: (route: PageDescriptor) => CompiledRoute;

/** The English defaults. A deployment overrides any subtree via
 *  {@link FallbackStringsProvider} or a per-component `strings` prop;
 *  unspecified keys fall through to these. */
export declare const defaultFallbackStrings: FallbackStrings;

/**
 * Split a loader's result into data that blocks the shell and data that
 * streams in after it.
 *
 * Legal in a PAGE loader on `renderMode: 'ssr'` + `interactive: 'full'`, and in
 * a LAYOUT loader that also serves a `renderMode:'spa'` page under it (the SSR
 * layout shell — streamed per request by `voltro dev` / `voltro serve`). Every
 * other combination is a hard boot/build error naming the page, because there
 * is no honest way to stream into a stored artefact or into a document with no
 * React runtime. See {@link assertDeferralSupported}.
 *
 * Deliberately NOT a `const` type parameter: a loader's `{ title: 'Ok' }` must
 * widen to `string`, the way any other loader's return type does. Pinning the
 * literal would make every page's data type change whenever a default string
 * in the loader changed.
 *
 * @param eager    values already resolved (or awaited by the loader itself)
 * @param deferred promises — NOT awaited by the loader
 */
export declare const defer: <TEager extends object, TDeferred extends Record<string, Promise<unknown>>>(eager: TEager, deferred: TDeferred) => DeferredLoaderResult<TEager, TDeferred>;

/** Brand key on the object `defer()` returns. A single explicit container
 *  check — NOT a scan of arbitrary loader results for markers by shape. */
declare const DEFERRED_RESULT_TAG: "__voltroDeferredLoaderResult";

/** What a loader returns when it defers part of its data. Opaque to user
 *  code: build it with {@link defer}, read it with `useLoaderData()`. */
export declare interface DeferredLoaderResult<TEager extends object = object, TDeferred extends Record<string, Promise<unknown>> = Record<string, Promise<unknown>>> {
    readonly [DEFERRED_RESULT_TAG]: true;
    /** Awaited before the shell renders — present in the SSR markup AND in the
     *  inlined `__voltro_state__` payload. */
    readonly eager: TEager;
    /** Streamed after the shell — each key becomes a promise on
     *  `useLoaderData()`, to be rendered through `<Await>`. */
    readonly deferred: TDeferred;
}

export declare interface DevStatus {
    /** Stable id; re-pushing the same id replaces the entry (lets a
     *  caller update its label without dropping + re-creating). */
    readonly id: string;
    readonly kind: DevStatusKind;
    /** Short label rendered inside the pill, e.g. "Compiling…". Kept
     *  under ~24 chars so the pill stays visually compact. */
    readonly label: string;
}

export declare type DevStatusKind = 'compiling' | 'loading' | 'reconnecting' | 'error';

export declare interface ErrorBoundaryProps {
    readonly error: unknown;
    readonly reset: () => void;
}

declare const EXTERNAL_URL_BRAND: unique symbol;

/**
 * Escape-hatch for any URL the codegen can't model: cross-origin
 * (`https://example.com`), `mailto:`, `tel:`, hash-only (`#section`),
 * or a sibling-app route the workspace scanner missed.
 *
 * The wrapper is a no-op at runtime — the brand exists purely for
 * compile-time `<Link to=…>` checks. The point is to force a deliberate
 * choice at the call-site instead of letting any string slip past.
 */
export declare const externalUrl: (url: string) => VoltroExternalUrl;

/** Every user-facing string the shipped fallback chrome renders. Scalars are
 *  literals; anything that interpolates a value is a function so a locale can
 *  reorder. English defaults live in {@link defaultFallbackStrings}. */
export declare interface FallbackStrings {
    /** <DefaultErrorFallback> — the runtime-error diagnostic card. */
    readonly error: {
        /** The muted brand tag at the top-right of the card. */
        readonly brandTag: string;
        /** The collapsible stack-trace disclosure summary. */
        readonly stackTrace: string;
        /** Primary action — in-place ErrorBoundary reset. */
        readonly retry: string;
        /** Secondary action — hard `window.location.reload()`. */
        readonly reload: string;
        /** Copy-to-clipboard button, idle label. */
        readonly copy: string;
        /** Copy button label after a successful clipboard write. */
        readonly copied: string;
        /** Copy button label after BOTH clipboard paths failed (points at the
         *  revealed manual-select block). */
        readonly copyFailed: string;
        /** The footer hint's bold heading. */
        readonly serverContextHeading: string;
        /** The footer hint prose. `command` is the pre-formatted `<code>` element
         *  for `voltro logs --since 30s` — a locale reorders the sentence around
         *  it but never translates the command itself. */
        readonly serverContextHint: (command: ReactNode) => ReactNode;
    };
    /** <DefaultNotFound> — the route-miss (404) card. */
    readonly notFound: {
        /** The pill tag at the top of the card. */
        readonly badge: string;
        /** The headline. */
        readonly heading: string;
        /** The body prose. `path` is the current pathname `<code>`, `pagesDir` the
         *  `*.page.tsx` `<code>` — a locale reorders the sentence around both. */
        readonly body: (path: ReactNode, pagesDir: ReactNode) => ReactNode;
    };
}

/** Provide localized (or otherwise overridden) fallback strings to the shipped
 *  default ErrorBoundary / NotFound chrome below. Overrides are deep-merged onto
 *  the English defaults — supply only the sections/keys you change. Nesting
 *  providers merges onto the parent. */
export declare function FallbackStringsProvider(props: {
    readonly strings: PartialFallbackStrings;
    readonly children: ReactNode;
}): ReactNode;

/**
 * Pick the not-found descriptor whose prefix is the longest match for
 * `pathname`. `''` (root) always matches as a last resort. Returns null
 * only if there are no descriptors at all.
 */
export declare const findNotFound: (notFounds: ReadonlyArray<NotFoundDescriptor>, pathname: string) => NotFoundDescriptor | null;

/** Browser-style printf substitution over a console call's args. Exported
 *  for direct unit coverage; the bridge below is its only runtime caller. */
export declare const formatPrintf: (args: ReadonlyArray<unknown>) => FormattedCall;

declare interface FormattedCall {
    readonly message: string;
    readonly rest: ReadonlyArray<unknown>;
}

/**
 * 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;

/** Read the latest snapshot. Returns a frozen-ish reference safe to
 *  use as a `useSyncExternalStore` getSnapshot result. */
export declare const getRouteSnapshot: () => RouteSnapshot;

/** Read the current set of statuses. Returns a STABLE reference —
 *  same array until the next mutation, so the result is safe to use
 *  as a `useSyncExternalStore` snapshot. */
export declare const getStatuses: () => ReadonlyArray<DevStatus>;

/**
 * Client-side runtime: scan the document for `[data-voltro-island]`
 * markers and schedule each for hydration per its strategy. Called once
 * at mount time by `@voltro/web/mount` when the page declares
 * `interactive: 'islands'`. Idempotent — running twice is a no-op (we
 * mark elements as visited).
 */
export declare const hydrateIslandsOnPage: () => void;

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';

declare const Image_2: ({ src, alt, width, height, fill, sizes, priority, loader, placeholder, blurDataURL, style, ...rest }: ImageProps) => ReactElement;
export { Image_2 as Image }

/** App-level default loader for every `<Image>` below it. A per-image
 *  `loader` prop overrides this. */
export declare const ImageConfigProvider: ({ loader, children, }: {
    readonly loader: ImageLoader;
    readonly children: ReactNode;
}) => ReactElement;

/** Maps a logical src + a target pixel width to a concrete URL. The hook
 *  for on-the-fly resizing — e.g. `({src,width}) => \`${src}?w=${width}\``
 *  against an image CDN or the storage serve endpoint. */
export declare type ImageLoader = (params: {
    readonly src: string;
    readonly width: number;
}) => string;

export declare interface ImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'width' | 'height' | 'loading' | 'srcSet'> {
    readonly src: string;
    /** Required — accessibility. Use `alt=""` for purely decorative images. */
    readonly alt: string;
    /** Intrinsic width in px. Required unless `fill`. */
    readonly width?: number;
    /** Intrinsic height in px. Required unless `fill`. */
    readonly height?: number;
    /** Absolutely fill the nearest positioned ancestor (object-fit: cover).
     *  Use instead of width/height when the container sizes the image. */
    readonly fill?: boolean;
    /** `sizes` media hint, e.g. `(max-width:768px) 100vw, 50vw`. Defaults to
     *  `100vw` under `fill`. */
    readonly sizes?: string;
    /** Above-the-fold / LCP image: eager-load + high fetch priority. */
    readonly priority?: boolean;
    /** Per-image URL loader (overrides the ImageConfigProvider default). */
    readonly loader?: ImageLoader;
    /** `'blur'` paints `blurDataURL` behind the image until it loads. */
    readonly placeholder?: 'blur' | 'empty';
    readonly blurDataURL?: string;
}

export declare const installBrowserConsoleBridge: (options: BrowserConsoleBridgeOptions) => BrowserConsoleBridge;

export declare const installServerLogRelay: (options: ServerLogRelayOptions) => ServerLogRelay;

/**
 * How the client-side JS hydrates a server-rendered page.
 *
 *   - 'full'    — Hydrate the entire page tree as one React root.
 *                 Default for `'spa'` pages and the safe default for
 *                 `'static'` pages that haven't been thought through.
 *                 Subscriptions + interactivity work everywhere.
 *   - 'islands' — Skip the full-tree hydration. The client runtime
 *                 only hydrates `<div data-voltro-island>` markers
 *                 emitted by `island()`. Other parts of the page stay
 *                 pure static HTML with no React lifecycle running.
 *                 Best perf for content-heavy pages with isolated
 *                 interactive zones.
 *
 * Defaults to `'full'` when not specified.
 */
export declare type InteractiveMode = 'full' | 'islands' | 'none';

/** True for exactly the object {@link defer} returns. */
export declare const isDeferredLoaderResult: (value: unknown) => value is DeferredLoaderResult;

/**
 * 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;
}

/** Brand guard — true for any `NotFoundError`, even one minted by a
 *  duplicate class identity in another bundle. */
export declare const isNotFound: (e: unknown) => e is NotFoundError;

/** Brand guard — true for any `RedirectError`, even cross-bundle. */
export declare const isRedirect: (e: unknown) => e is RedirectError;

/** Join an origin (`https://example.com`, optionally with a trailing slash) to a
 *  root-relative path, collapsing the slash seam so exactly one separates them. */
export declare const joinUrl: (siteUrl: string, path: string) => string;

/** Lazy variant of `pageRoute`: takes a thunk that dynamically imports the page
 *  instead of an already-imported module. The chunk loads only when the route
 *  first matches — the initial bundle no longer pulls in every page. */
export declare const lazyPageRoute: (pattern: string, load: () => Promise<Record<string, unknown>>, extras?: {
    readonly chain?: ReadonlyArray<RouteSegment>;
}) => PageDescriptor;

export declare const Link: ({ to, children, onClick, prefetch: prefetchProp, replace, onMouseEnter, onFocus, ref, ...anchorProps }: LinkProps) => ReactNode;

export declare interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href' | 'onClick'> {
    readonly to: VoltroUrl;
    readonly children: ReactNode;
    readonly onClick?: (event: MouseEvent_2<HTMLAnchorElement>) => void;
    /** When and how to pre-warm the destination. See {@link PrefetchMode}. */
    readonly prefetch?: PrefetchMode;
    /** Swap the current history entry instead of pushing a new one —
     *  mirror of `NavigateOptions.replace`. */
    readonly replace?: boolean;
    /**
     * Forwarded to the underlying `<a>`.
     *
     * It already WAS, at runtime — every prop this component does not consume
     * itself is spread onto the anchor, `ref` included, and React 19 passes it to
     * a function component as an ordinary prop. Only the type did not say so, and
     * `AnchorHTMLAttributes` does not carry `ref`. So any polymorphic slot that
     * threads one through — MUI's `<Button component={Link}>`, Chakra's `as`,
     * anything with a `component=` escape hatch — was a type error against
     * behaviour that worked, and had to be shimmed in every consumer.
     */
    readonly ref?: Ref<HTMLAnchorElement>;
}

export declare class LoaderCache {
    private readonly entries;
    get(key: string): LoaderEntry | undefined;
    /**
     * Start a loader run for `key` if one isn't already in flight (or settled).
     * Returns the entry — callers can wait on `.promise` for pending entries.
     *
     * `run` is invoked SYNCHRONOUSLY so callers (and tests) can observe its
     * single-call semantics without first flushing a microtask. Sync throws
     * are caught and surface as a rejected entry just like async rejections.
     */
    start<T>(key: string, run: (signal: AbortSignal) => Promise<T> | T): LoaderEntry<T>;
    /** Abort a pending loader; preserves settled (success/error) entries. */
    abort(key: string): void;
    /** Drop entries matching `pattern` (any params). */
    invalidate(pattern: string): void;
    /**
     * Install an already-settled result for `key` without running anything.
     * Used to adopt server-rendered loader data at hydration: the entry is
     * `success` from the start, so the router's loader effect collects it
     * immediately and the loader never re-runs on the initial render.
     *
     * Never overwrites an existing entry — a loader that a navigation already
     * started (or settled) outranks a stale seed.
     */
    seed(key: string, data: unknown): void;
    /** Drop every entry. Test-only escape hatch. */
    clear(): void;
}

export declare const loaderCacheKey: (pattern: string, params: Readonly<Record<string, string>>) => string;

/**
 * What a `loader` receives.
 *
 * **It runs on the server AND again in the browser.** A loader is not a
 * server-only hook: it runs during SSR for the first paint, and then runs
 * AGAIN, in the browser, on every in-app navigation to the route. Same
 * function, different environment.
 *
 * That precondition was never written down, and a deployment read "runs once per
 * request" into the gap — which is the reading the wording invites. It cost
 * them two days, and the reason it survived that long is the nastiest part: a
 * client-only failure is invisible to every probe that does not NAVIGATE. A
 * fresh page load, a `curl`, any SSR check goes through the server path and
 * passes. Only clicking a link inside the running app reaches the other one.
 *
 * So anything server-only in a loader must be guarded by {@link isServer}.
 */
export declare interface LoaderContext<Procedures = unknown> {
    readonly params: Readonly<Record<string, string>>;
    readonly pathname: string;
    /**
     * `true` when this invocation is the SERVER one (SSR under `voltro dev` or
     * `voltro start`), `false` in the browser.
     *
     * Exists because the alternatives are traps. `query` is absent in the browser
     * and so reads as a discriminator, but branching on the ABSENCE OF A FUNCTION
     * says nothing about why it is absent and breaks the moment anything else
     * becomes conditional. `headers` is worse: it is `{}` in the browser, not
     * `undefined`, so `ctx.headers ? …` is TRUE on both paths — a deployment
     * checked exactly that and it silently did nothing.
     *
     *     export const loader = async (ctx: LoaderContext) => {
     *       if (ctx.isServer) seedStore(prefs, await ctx.query!('prefs.get'))
     *       return null
     *     }
     *
     * REQUIRED, not optional: an optional boolean is omissible, and a server path
     * that forgot it would read as `undefined` — falsy — and claim to be the
     * browser. Required means the compiler names every construction site.
     */
    readonly isServer: boolean;
    /**
     * The raw query string, INCLUDING the leading `?`, or `''` when there is
     * none. Filled on every path — client navigation, `voltro dev` SSR and
     * `voltro start` SSR.
     *
     * `pathname` deliberately excludes the query string, and for DATA that is
     * right: a loader keyed on `?tab=2` would cache badly. It is wrong for
     * CONTROL FLOW, which is what a loader does when it throws `RedirectError` —
     * a redirect target routinely depends on a query parameter, and until this
     * existed the only place a redirect belongs was the only place without access
     * to it.
     *
     * The reported case: a page redirects an unknown code back to the entry page
     * and must preserve `?mode=kiosk`, or a kiosk terminal drops to normal mode
     * after every failed scan. Both workarounds are bad — moving the redirect
     * into a component gives up the 303, and `window.location.search` only exists
     * on the client-navigation path, so a fresh SSR request loses the mode.
     *
     * Parse it with `new URLSearchParams(ctx.search)`.
     */
    readonly search: string;
    /** Aborted when the user navigates away before the loader resolves. */
    readonly signal: AbortSignal;
    /** Request headers when the loader runs server-side via `voltro
     *  start`. Lowercased keys. Empty `{}` for client-side loader
     *  invocations (browser-fetch goes through the rpc layer, not the
     *  loader). Use this for tenant resolution, auth headers, etc.
     *  until the auth slice ships a typed Subject. */
    readonly headers?: Readonly<Record<string, string>>;
    /** Server-side one-shot rpc fetch. Invokes any backend rpc (queries
     *  included — the FIRST snapshot of a streaming query is resolved and
     *  returned) over the api's HTTP rpc surface (`POST /rpc`), forwarding
     *  the request's `cookie` header so the api resolves the same Subject +
     *  tenant the WS path would. Bound to the app's single / first api.
     *
     *  Present ONLY when the loader runs server-side (`voltro start` /
     *  `voltro dev` SSR). `undefined` for client-side loader invocations —
     *  in the browser, use `useSubscription` in the component for live data
     *  instead; the loader's `query` is for SSR first-paint + `meta`.
     *
     *  UNTYPED by default, and typed by naming your app's procedure map — the
     *  same map `createHooks` already takes, and the same extraction, so the two
     *  cannot disagree about what a tag returns:
     *
     *      import type { AppProcedures } from '<your-api>/rpcGroup'
     *
     *      export const loader = async ({ query }: LoaderContext<AppProcedures>) => {
     *        const rows = await query?.('bookmarks.list', { limit: 100 })
     *        //    ^ inferred from the descriptor, and an unknown tag is an error
     *      }
     *
     *  The default parameter keeps every existing loader compiling: with no map
     *  the signature is the old `<T = unknown>(tag: string, …)`. It is opt-in for
     *  the same reason `createHooks<AppProcedures>` is — the framework cannot
     *  import an app's generated file, so the app has to name it. */
    readonly query?: LoaderQuery<Procedures>;
}

/**
 * What `useLoaderData<T>()` hands the component for a loader returning `T`.
 * A plain loader is unchanged (`LoaderData<X>` is `X`); a deferring loader
 * flattens to its eager fields PLUS a promise per deferred field, which is
 * exactly what `<Await value={...}>` consumes.
 */
export declare type LoaderData<TLoaderResult> = TLoaderResult extends DeferredLoaderResult<infer TEager, infer TDeferred> ? {
    readonly [K in keyof (TEager & TDeferred)]: (TEager & TDeferred)[K];
} : TLoaderResult;

/* Excluded from this release type: LoaderDataContext */

declare type LoaderEntry<T = unknown> = {
    readonly status: 'pending';
    readonly promise: Promise<void>;
    readonly controller: AbortController;
} | {
    readonly status: 'success';
    readonly data: T;
} | {
    readonly status: 'error';
    readonly error: unknown;
};

export declare type LoaderFn<T = unknown, Procedures = unknown> = (ctx: LoaderContext<Procedures>) => Promise<T> | T;

/**
 * The loader's server-side `query`, typed by a procedure map when one is given.
 *
 * Reuses `ProcedureInput` / `ProcedureOutput` from `@voltro/client` rather than
 * re-deriving them. A second extraction would be a second answer to "what does
 * this tag return", and the two would drift the first time a descriptor field
 * is renamed — the shape this repo already has scars from.
 */
export declare type LoaderQuery<Procedures = unknown> = Procedures extends ProcedureTypeMap ? <Tag extends keyof Procedures & string>(tag: Tag, ...input: Record<string, never> extends ProcedureInput<Procedures[Tag]> ? [input?: ProcedureInput<Procedures[Tag]>] : [input: ProcedureInput<Procedures[Tag]>]) => Promise<ProcedureOutput<Procedures[Tag]>> : <T = unknown>(tag: string, input?: Record<string, unknown>) => Promise<T>;

/** The URL path a logical page takes for a given locale under URL-prefix
 *  routing: the default locale keeps the bare path, every other locale gets a
 *  `/<locale>` prefix. `/about` @ `de` → `/de/about`; @ the default → `/about`. */
export declare const localizedPath: (path: string, locale: string, defaultLocale: string) => string;

export declare const matchRoute: (compiled: ReadonlyArray<CompiledRoute>, pathname: string) => RouteMatch | null;

/**
 * Boot the framework's React stack against the given app. Resolves the
 * typed rpc client for each api in parallel, renders the user's component
 * tree inside the framework runtime + clients providers, and in dev mode
 * auto-recovers each client in-place when its dev server restarts.
 */
export declare const mount: (App: ComponentType, options: MountOptions) => void;

export declare interface MountApiSpec<Rpcs extends Rpc.Any = Rpc.Any> {
    /** The RpcGroup this api speaks. */
    readonly group: RpcGroup.RpcGroup<Rpcs>;
    /** Per-rpc-tag descriptor metadata: `{ kind, source?, targets? }`. The
     *  framework's auto-optimistic flow reads this to know which mutation
     *  affects which cached query. The CLI's codegen emits it as
     *  `appDescriptors` next to `appGroup`. */
    readonly descriptors?: Readonly<Record<string, {
        readonly kind: 'query' | 'mutation' | 'action' | 'stream' | 'workflow';
        readonly source?: string;
        readonly targets?: ReadonlyArray<{
            readonly table: string;
            readonly op: 'insert' | 'update' | 'delete';
            readonly order?: 'prepend' | 'append';
        }>;
    }>>;
    /** Explicit WebSocket URL for this api. Required for external apis
     *  (where there's no Vite proxy). Defaults to same-origin `/ws/<name>`
     *  for workspace apis served via the framework's dev proxy. */
    readonly wsUrl?: string;
    /** Auth headers sent with EVERY rpc request over the socket — this is how
     *  a cross-origin api authenticates WS subscriptions. They ride in the
     *  @effect/rpc message frame, NOT the WS handshake (a browser can't set
     *  upgrade headers). Pass a thunk to fetch a rotating token fresh on every
     *  (re)connect, e.g. `headers: async () => ({ authorization: 'Bearer ' +
     *  (await supabase.auth.getSession()).data.session?.access_token })`; a
     *  static object is also accepted. Do NOT hardcode a secret literal — it
     *  ships to the client and is visible in source; resolve it at runtime. */
    readonly headers?: ResolvableHeaders;
}

export declare interface MountOptions {
    /** Map of api name → spec. The name is the lookup key for hooks
     *  (`useAppClient<T>(name)`, `useSubscription(name, ...)`, etc.). */
    readonly apis: Record<string, MountApiSpec>;
    /** Override the root element id. Defaults to 'root'. */
    readonly rootId?: string;
    /** Optional in-page devtools overlay component. Wired up by the
     *  CLI's generated `main.tsx` when `import.meta.env.DEV` is truthy
     *  and the app hasn't set `disableDevtools` in app.config.ts.
     *  Renders INSIDE the FrameworkBoot tree so its hooks
     *  (useFrameworkRuntimes, useLoaderData, …) resolve normally.
     *  PascalCase because it is a React component reference rendered
     *  as <Devtools/>. */
    readonly Devtools?: ComponentType;
}

/** Options for an imperative navigation. `replace` swaps the current
 *  history entry instead of pushing a new one — what a loader redirect
 *  wants so Back doesn't bounce the user onto the page that redirected. */
export declare interface NavigateOptions {
    readonly replace?: boolean;
    /** Set to `false` to preserve the current scroll position. Defaults to true. */
    readonly scroll?: boolean;
}

export declare const NavigationIndicator: () => ReactNode;

/* Excluded from this release type: NO_LOADER_DATA */

/** Strip a trailing slash from a path, except the root, and guarantee a leading
 *  slash. `''` and `'/'` both normalise to `'/'`. */
export declare const normalizePath: (path: string) => string;

/** Construct-and-throw sugar for `NotFoundError`. Typed `: never` so
 *  control-flow narrows at the call site (`const x = row ?? notFound()`). */
export declare const notFound: (detail?: string) => never;

/**
 * Stand-alone descriptor for URL prefixes that have no concrete page but
 * SHOULD respond to unmatched subpaths with a scoped `not-found.tsx`. The
 * router picks the longest-prefix match.
 */
export declare interface NotFoundDescriptor {
    /** Path prefix this not-found is responsible for. `''` = root. */
    readonly prefix: string;
    readonly Component: ComponentType;
    readonly chain?: ReadonlyArray<RouteSegment> | undefined;
}

/** Thrown from a loader to render the scoped `not-found.tsx` subtree
 *  (client nav) / emit a 404 (SSR / SSG). */
export declare class NotFoundError extends Error {
    readonly _voltroControl: "not-found";
    constructor(detail?: string);
}

export declare const noticeIslandsShipTheFullBundle: (isDev: boolean) => void;

export declare const PAGE_SLOT_ATTR = "data-voltro-page-slot";

export declare interface PageDescriptor<TLoaderData = unknown> {
    /** URL pattern, e.g. `/`, `/about`, `/users/[id]`, `/docs/[...slug]`. */
    readonly pattern: string;
    /** The page component. Present on eager routes; on a LAZY route (see
     *  `load`) it's filled by the Router once the page chunk has loaded. */
    readonly Component?: ComponentType | undefined;
    /** LAZY route: a thunk that dynamically imports the page module. When set,
     *  the page chunk is fetched only when this route first matches, so the
     *  initial bundle never imports every page. The Router resolves
     *  `Component` / `loader` / `meta` / … from the loaded module; the layout
     *  `chain` stays eager. */
    readonly load?: (() => Promise<Record<string, unknown>>) | undefined;
    /** Static meta, or a function of `{ params, loaderData, locale }` —
     *  so a document title can read what the page loader fetched (the
     *  dynamic metadata case) AND can localise per-locale at SSG time
     *  for URL-prefix i18n routing. `loaderData` is the page loader's
     *  result; `locale` is the active i18n locale during pre-render
     *  (driven by `params.locale` for `[locale]/...` routes, falling
     *  back to the app's defaultLocale). On the client, `locale` is
     *  the URL-derived locale when the route is locale-prefixed,
     *  otherwise the framework's resolved locale (cookie / Accept-
     *  Language / default). */
    readonly meta?: PageMeta | ((ctx: {
        readonly params: Readonly<Record<string, string>>;
        readonly loaderData: unknown;
        readonly locale: string;
    }) => PageMeta) | undefined;
    /** Async data preload; result available via useLoaderData<T>(). */
    readonly loader?: LoaderFn<TLoaderData> | undefined;
    /** Catches render + loader errors for THIS leaf. Tighter scope than `chain[*].Error`. */
    readonly ErrorBoundary?: ComponentType<ErrorBoundaryProps> | undefined;
    /** Shown while the loader is in flight (first navigation to the route). */
    readonly Pending?: ComponentType | undefined;
    /**
     * Outer-to-inner layer chain. Each segment maps to one directory level
     * (or route group) on the way from the pages root down to this leaf.
     * Codegen produces this from the discovery walk; user code rarely
     * writes it by hand.
     */
    readonly chain?: ReadonlyArray<RouteSegment> | undefined;
    /** How the page's HTML is produced. Defaults to 'static' so pages
     *  pre-render by default — SEO + first-paint speed are wins users
     *  pay nothing for. Opt out with `'spa'` for pages that need a
     *  per-request render. */
    readonly renderMode?: RenderMode | undefined;
    /** How the page's client-side JS hydrates. Defaults to `'full'`
     *  (whole tree). Pages designed around the islands pattern should
     *  set this to `'islands'` so only marked interactive zones
     *  hydrate; the rest stays pure static HTML. */
    readonly interactive?: InteractiveMode | undefined;
}

export declare interface PageMeta {
    readonly title?: string;
    readonly description?: string;
    /** Canonical URL for this page. Emitted as `<link rel="canonical">`.
     *  Relative paths are accepted — search engines resolve them
     *  against the document's base URL. Use this on duplicated routes
     *  (locale variants, alternate URL forms) to declare the preferred
     *  one indexable URL. */
    readonly canonical?: string;
    /** Arbitrary additional meta tags. `name` OR `property` is required. */
    readonly tags?: ReadonlyArray<{
        readonly name?: string;
        readonly property?: string;
        readonly content: string;
    }>;
    /** Arbitrary additional `<link>` tags. Use for `alternate` hreflang,
     *  prev/next pagination, RSS feeds, manifest, etc. (For the common
     *  canonical case, prefer the dedicated `canonical` field above.) */
    readonly links?: ReadonlyArray<{
        readonly rel: string;
        readonly href: string;
        readonly hreflang?: string;
        readonly type?: string;
        readonly title?: string;
    }>;
    /** JSON-LD structured-data payloads. Each entry is emitted as a
     *  separate `<script type="application/ld+json">` so search engines
     *  and LLM crawlers can pick up rich metadata (Article, Product,
     *  SoftwareApplication, BreadcrumbList, FAQPage, etc.). Anything
     *  JSON-serialisable is accepted; `@context` + `@type` are
     *  authored, not synthesised. */
    readonly jsonLd?: ReadonlyArray<Record<string, unknown>>;
    /** Keep this page out of the index. Emits
     *  `<meta name="robots" content="noindex, nofollow">`, and the build's
     *  `sitemap.xml` generator EXCLUDES the route. Use for utility pages
     *  (checkout steps, previews, thank-you pages) that should not rank. */
    readonly noIndex?: boolean;
}

export declare const pageRoute: (pattern: string, mod: Record<string, unknown>, extras?: {
    readonly chain?: ReadonlyArray<RouteSegment>;
}) => PageDescriptor;

/** The empty page slot the SSR-layout-shell path renders at the leaf, on BOTH
 *  the server (`renderPageToHtml` with `pageSlot`) and the client Router's
 *  first render — identical markup, so hydration matches. */
export declare const PageSlot: () => ReactNode;

export declare const parseCookieHeader: (raw: string | undefined) => Record<string, string>;

/** A caller may override any subtree, not the whole object — deep-partial per
 *  section (each section is a flat bag of literals/functions, so a shallow
 *  per-section merge is exact). */
export declare type PartialFallbackStrings = {
    readonly [K in keyof FallbackStrings]?: Partial<FallbackStrings[K]>;
};

/** Default: no resizing — every candidate width resolves to the same URL.
 *  Still emits a (degenerate) srcSet so swapping in a real loader is a
 *  one-line change with no call-site churn. */
export declare const passthroughImageLoader: ImageLoader;

export declare const PlainLink: (props: PlainLinkProps) => ReactNode;

export declare interface PlainLinkProps {
    readonly to: string;
    readonly children: ReactNode;
    readonly className?: string;
    readonly style?: React.CSSProperties;
    readonly onClick?: (event: MouseEvent_2<HTMLAnchorElement>) => void;
    readonly prefetch?: PrefetchMode;
}

/**
 * When a link pre-warms its destination — both the route's loaders AND its
 * lazy page chunk.
 *
 * - `false` (default) — never.
 * - `true` / `'hover'` — on pointer-enter and on focus. Costs nothing until
 *   the user shows intent, which is why it is the safe default to reach for.
 * - `'visible'` — additionally as soon as the link scrolls into view
 *   (IntersectionObserver, 128px ahead). Right for a short, deliberate set of
 *   links (a nav bar, "next chapter"); wrong for a long list, where it turns
 *   a scroll into one request per row.
 */
export declare type PrefetchMode = boolean | 'hover' | 'visible';

/**
 * Preload the page module for the route matching `pathname`, when that route is
 * lazy. `load()` fetches the chunk AND — via the codegen's lazy thunk — records
 * the module in the app's `refs.pages` registry, so the NEXT `buildRoutes()`
 * yields an EAGER route for it.
 *
 * The generated `main.tsx` awaits this for the current URL BEFORE `hydrateRoot`
 * whenever it's hydrating pre-rendered HTML. Without it, the client's first
 * render resolves a lazy leaf to `null` (its chunk hasn't loaded yet) while the
 * SSG/SSR HTML rendered the full page — a `<main>`-content hydration mismatch
 * (React #418) that regenerates the tree and shifts every `useId` beneath it.
 * With the module preloaded, the first client render matches the server exactly.
 *
 * No-op for eager routes (already resolvable) or an unmatched path. A failed
 * chunk load is swallowed here — it surfaces via the leaf error boundary when
 * the route renders.
 */
export declare const preloadRouteModule: (routes: ReadonlyArray<PageDescriptor>, pathname: string) => Promise<void>;

/** Publish a status. Returns the dispose handle — call it when the
 *  underlying work finishes. Safe to call dispose twice. */
export declare const pushStatus: (status: DevStatus) => (() => void);

export declare const ReconnectContext: Context<(() => void) | null>;

/** Construct-and-throw sugar for `RedirectError`. Typed `: never`. */
export declare const redirect: (location: string, opts?: {
    readonly status?: 303 | 307 | 308;
}) => never;

/** Thrown from a loader to redirect: 3xx + `Location` on SSR, a
 *  client-side `navigate(..., { replace: true })` on the SPA path. */
export declare class RedirectError extends Error {
    readonly _voltroControl: "redirect";
    readonly location: string;
    readonly status: 303 | 307 | 308;
    constructor(location: string, opts?: {
        readonly status?: 303 | 307 | 308;
    });
}

export declare const registerClientTrace: (traceId: string) => void;

/**
 * How a page's HTML is produced.
 *
 *   - 'static'  — Pre-rendered to flat HTML at build time. Default.
 *                 Shipped as `dist/<route>/index.html`. JS bundle
 *                 still loads to hydrate islands + handle SPA-style
 *                 navigation, but the first paint is instant + SEO
 *                 friendly. Loaders MUST be side-effect-free + must
 *                 not require per-request context (subject, headers).
 *   - 'spa'     — Client-only rendering. No HTML pre-render; the
 *                 shipped HTML is a shell that mounts on the
 *                 client. Useful for pages that genuinely need a
 *                 fresh client render every load (most reactive
 *                 dashboards).
 *
 *   - 'ssr'  — Rendered on every request, server-side, via `voltro
 *               start`. Loaders run per request with access to
 *               `headers` + `query` (the api HTTP rpc); the resolved
 *               HTML is sent fresh each time. Use for personalised /
 *               tenant-scoped first paint.
 *   - 'isr'  — Like 'ssr' on the first request, then cached and
 *               revalidated in the background on a TTL.
 *
 * The value set is single-sourced from {@link RENDER_MODES} so the type and
 * every runtime check derive from ONE literal list. There are no aliases — an
 * unrecognised value is rejected at codegen/discovery time by the CLI, not
 * silently passed through.
 */
export declare const RENDER_MODES: readonly ["static", "spa", "ssr", "isr"];

/**
 * A page's render mode — one of {@link RENDER_MODES}, from which this type is
 * derived. Closed set: an unrecognised value is rejected at codegen time.
 */
export declare type RenderMode = (typeof RENDER_MODES)[number];

/* Excluded from this release type: renderRouterProviderTree */

/**
 * Decide whether a click on (or inside) an anchor should be handled by the
 * SPA router or left to the browser. Pure — no side effects, no
 * `preventDefault`. The caller performs the navigation + preventDefault
 * when the result is `'spa'`.
 *
 * Returns `'native'` (browser handles it) when ANY of:
 *   - the event was already handled (`defaultPrevented` — a `<Link>` ran)
 *   - it's not a plain left-click (middle/right click, any modifier key)
 *   - no enclosing `<a>`, or the anchor has no `href`
 *   - the anchor targets another browsing context (`target` ≠ `_self`)
 *   - the anchor is a download, `rel="external"`, or opts out (`data-no-spa`)
 *   - the resolved URL is cross-origin
 *   - the resolved URL is a pure in-page hash on the current page
 *
 * Otherwise returns `'spa'` with the path+search+hash to navigate to.
 *
 * `currentHref` is the document's current URL (`location.href`) — passed in
 * so the function is deterministic and unit-testable.
 */
export declare const resolveAnchorNavigation: (event: {
    readonly defaultPrevented: boolean;
    readonly button: number;
    readonly metaKey: boolean;
    readonly ctrlKey: boolean;
    readonly shiftKey: boolean;
    readonly altKey: boolean;
    readonly target: EventTarget | null;
}, currentHref: string) => AnchorNavigationDecision;

export declare type ResolvedTheme = 'light' | 'dark';

export declare const resolveMeta: (meta: PageDescriptor["meta"], params: Readonly<Record<string, string>>, loaderData?: unknown, locale?: string) => PageMeta | null;

declare const ROUTE_URL_BRAND: unique symbol;

export declare interface RouteMatch {
    readonly route: CompiledRoute;
    readonly params: Readonly<Record<string, string>>;
}

export declare const Router: ({ routes, notFounds, notFound: NotFound, errorFallback: ErrorFallback, }: RouterProps) => ReactNode;

/* Excluded from this release type: RouterContext */

declare interface RouterContextValue {
    readonly pathname: string;
    /** `search + hash` of the current URL (e.g. `?tab=skills#x`). Tracked in
     *  state so query-param-only navigations (same pathname) still re-render
     *  consumers — `useSearchParams`/`useLocation` would otherwise go stale
     *  until an unrelated re-render. */
    readonly search: string;
    readonly navigate: (to: string, opts?: NavigateOptions) => void;
    readonly params: Readonly<Record<string, string>>;
    readonly prefetch: (to: string) => void;
    /** Internal: loader data for the active match. */
    readonly loaderData: unknown;
    /** Internal: register a navigation guard; returns an unregister fn.
     *  Consumed by `useBlocker`. */
    readonly registerBlocker: (id: symbol, fn: BlockerFn) => () => void;
    /** Internal: the navigation currently held back by a blocker, if any.
     *  Consumed by `useBlocker` to surface `retry`/`reset` to the caller. */
    readonly blocked: BlockedNavigation | null;
}

export declare interface RouterProps {
    readonly routes: ReadonlyArray<PageDescriptor>;
    /**
     * Per-prefix not-found descriptors. Router picks the longest-prefix
     * match when no concrete route hits. `notFound` (component) is the
     * fallback for paths without any matching prefix.
     */
    readonly notFounds?: ReadonlyArray<NotFoundDescriptor>;
    readonly notFound?: ComponentType;
    /** Fallback ErrorBoundary used when neither the leaf nor its chain supplies one. */
    readonly errorFallback?: ComponentType<ErrorBoundaryProps>;
}

/**
 * One layer in a page's nesting chain. Each represents a directory level
 * in the file-convention layout (or a route group).
 *
 * Layouts wrap their children — outer layers wrap inner ones. Errors are
 * caught by the deepest layer with an `Error` component; if none, the
 * error bubbles up the chain. NotFound applies when an URL is under this
 * layer's scope but no concrete page matches.
 *
 * The chain persists across navigation within its scope — React preserves
 * the layout component instances because their position in the tree is
 * stable for any leaf within that subtree.
 */
export declare interface RouteSegment {
    /** Outer-vs-inner ordering label (debug only). */
    readonly id?: string | undefined;
    readonly Layout?: ComponentType<{
        children: ReactNode;
    }> | undefined;
    readonly Error?: ComponentType<ErrorBoundaryProps> | undefined;
    readonly Pending?: ComponentType | undefined;
    readonly NotFound?: ComponentType | undefined;
    /** Async data preload for THIS layout level. Runs in parallel with the
     *  page loader (and the other layouts') before mount; the result is
     *  reachable via `useLoaderData<T>()` from INSIDE this layout (each
     *  level sees its own loader's data). A `layout.tsx` exports it like a
     *  page does — codegen wires it onto the segment. Server-side it
     *  receives request `headers` (session/tenant resolution). */
    readonly loader?: LoaderFn | undefined;
}

declare interface RouteSnapshot {
    readonly pathname: string;
    readonly params: Readonly<Record<string, string>>;
    /** Loader-resolved data for the active route. `undefined` when the
     *  route has no loader OR the loader rejected. */
    readonly loaderData: unknown;
}

/** The next search-params value: either the params object directly, or an
 *  updater that receives the CURRENT `URLSearchParams` and returns the next. */
export declare type SearchParamsInit = URLSearchParams | Readonly<Record<string, string>> | ((current: URLSearchParams) => URLSearchParams | Record<string, string>);

/**
 * Cache key for a layout (chain segment) loader. Distinct from the page's
 * key for the same (pattern, params) so a layout's data and the page's
 * never collide. `index` is the segment's position in the outer→inner
 * chain. Defined above `loaderCacheKey`'s body via the shared formatter.
 */
export declare const segmentLoaderKey: (pattern: string, index: number, params: Readonly<Record<string, string>>) => string;

/**
 * Compute the canonical URL + the full set of `hreflang` alternates for a
 * localized page. Spread the result straight into a `PageMeta`:
 *
 *     export const meta = ({ locale }) => ({
 *       title: t('about.title'),
 *       ...seoAlternates({
 *         siteUrl: 'https://example.com', path: '/about',
 *         locale, locales: ['en', 'de'], defaultLocale: 'en',
 *       }),
 *     })
 *
 * `canonical` is the current locale's absolute URL; `links` carries one
 * `rel="alternate"` per locale (each an ABSOLUTE URL — Google ignores relative
 * hreflang hrefs) plus the `x-default`. Every page in a locale set should point
 * its alternates at the SAME set of URLs, including a self-referential one, per
 * Google's reciprocity rule — which is exactly what iterating `locales` here
 * produces.
 */
export declare const seoAlternates: (input: SeoAlternatesInput) => {
    readonly canonical: string;
    readonly links: ReadonlyArray<SeoLink>;
};

export declare interface SeoAlternatesInput {
    /** Production origin, e.g. `'https://voltro.dev'`. Absolute URLs are required
     *  for `hreflang` alternates to be valid, so this is not optional. */
    readonly siteUrl: string;
    /** The page's LOGICAL path WITHOUT any locale prefix — the path as the default
     *  locale serves it (`/plugins/foo`, `/about`, `/`). The current locale's
     *  prefix is applied by this function, not by the caller. */
    readonly path: string;
    /** The locale THIS render is for — drives which URL is `canonical`. */
    readonly locale: string;
    /** Every locale the site publishes this page under. */
    readonly locales: ReadonlyArray<string>;
    /** The locale served at the bare (un-prefixed) path. */
    readonly defaultLocale: string;
    /** Emit an `hreflang="x-default"` alternate pointing at the default-locale URL
     *  (the recommended fallback for an unmatched language). Default `true`. */
    readonly xDefault?: boolean;
}

/** A `<link>` descriptor, structurally the entries `PageMeta.links` accepts. */
export declare interface SeoLink {
    readonly rel: string;
    readonly href: string;
    readonly hreflang?: string;
}

export declare interface ServerLogRelay {
    readonly dispose: () => void;
}

export declare interface ServerLogRelayOptions {
    /** HTTP(S) origin the CLI exposes the inspect stream on. */
    readonly baseUrl: string;
    /** Short label included in every emitted prefix — typically the api
     *  name ("cloud") or "web". Helps disambiguate multi-source streams. */
    readonly originLabel: string;
}

export declare const ServerRequestContext: Context<ServerRequestContextValue | null>;

export declare interface ServerRequestContextValue {
    readonly cookies: Readonly<Record<string, string>>;
    readonly headers: Readonly<Record<string, string>>;
    /** Raw request URL as it came off the wire (path + query). Useful
     *  for SSR pages that need to read `?q=…` style search params
     *  without touching anything client-only. Empty string for build-
     *  time SSG renders where there is no incoming request. */
    readonly url: string;
}

export declare const ServerRequestProvider: ({ value, children, }: {
    readonly value: ServerRequestContextValue;
    readonly children: ReactNode;
}) => ReactNode;

/** Push a new route snapshot. Router calls this from its render
 *  effect; observers re-render on the next microtask. */
export declare const setRouteSnapshot: (next: RouteSnapshot) => void;

/** How a `useSetSearchParams` write should update history. Defaults to
 *  `replace` — a filter/tab tweak shouldn't stack a Back entry per keystroke. */
export declare interface SetSearchParamsOptions {
    /** Push a new history entry instead of replacing the current one. */
    readonly push?: boolean;
    /** Set to `false` to preserve the current scroll position. Defaults to true. */
    readonly scroll?: boolean;
}

/**
 * Stable-sort compiled routes by ascending priority, so that more-specific
 * routes (lower priority) match before less-specific ones. Static beats
 * dynamic; dynamic beats catch-all. Within the same priority bucket,
 * declaration order is preserved.
 */
export declare const sortRoutesByPriority: (compiled: ReadonlyArray<CompiledRoute>) => ReadonlyArray<CompiledRoute>;

/** Subscribe to snapshot changes. Returns the unsubscribe function. */
export declare const subscribeRouteSnapshot: (cb: () => void) => (() => void);

/** Subscribe to changes. Returns the unsubscribe function. */
export declare const subscribeStatuses: (cb: () => void) => (() => void);

/** Subscribe to surfaced trace errors. Returns an unsubscribe fn. */
export declare const subscribeTraceErrors: (listener: TraceErrorListener) => () => void;

export declare type Theme = 'light' | 'dark' | 'system';

/** The cookie the pre-paint script reads. Keep in lockstep with `webDev.ts`. */
export declare const THEME_COOKIE = "voltro:theme";

export declare interface ThemeState {
    /** The stored PREFERENCE. `'system'` when no explicit choice is stored. */
    readonly theme: Theme;
    /** What is actually applied right now — `'system'` resolved against the OS. */
    readonly resolvedTheme: ResolvedTheme;
    /** Persist a preference (or `'system'` to clear it) and apply it immediately. */
    readonly setTheme: (theme: Theme) => void;
}

export declare interface TraceErrorEvent {
    /** Trace id (32 hex) — the same id `voltro logs --trace <id>` accepts. */
    readonly traceId: string;
    /** Span that failed (e.g. `rpc.mutation`, `webhook/stripe`). */
    readonly spanName: string;
    /** Which api the failed span ran in (the relay's originLabel). */
    readonly api: string;
    /** Error message from the span status. */
    readonly message: string;
    /** When the overlay received it. */
    readonly ts: number;
}

declare type TraceErrorListener = (event: TraceErrorEvent) => void;

/**
 * Returns the typed rpc client mounted under `apiName`. Generic narrows
 * the result to the caller's group; pass `typeof appGroup` from the api's
 * generated rpcGroup module:
 *
 *   import type { appGroup } from '@app/api/rpcGroup'
 *   import type { RpcClient, RpcGroup } from '@effect/rpc'
 *   type ApiClient = RpcClient.RpcClient<RpcGroup.Rpcs<typeof appGroup>>
 *
 *   const client = useAppClient<ApiClient>('api')
 *   const { data } = useSubscription('api', () => client.todos.list({}), [])
 *
 * Throws if no api is mounted under `apiName` (typo, missing entry in
 * app.config.ts, or app not mounted yet).
 */
export declare const useAppClient: <Client>(apiName: string) => Client;

/**
 * Block SPA navigations while `shouldBlock` is true — the unsaved-changes
 * guard. When the user tries to leave (a `<Link>` click, an intercepted
 * anchor, or an imperative `navigate`) and `shouldBlock` returns true, the
 * navigation is HELD and this hook returns `{ blocked: true, retry, reset }`
 * so you can render a confirm prompt: `retry()` proceeds, `reset()` stays.
 * A full-page unload (tab close / reload) additionally triggers the browser's
 * native `beforeunload` prompt while any blocker is active.
 *
 * ```tsx
 * const blocker = useBlocker(form.isDirty)
 * // …
 * {blocker.blocked && (
 *   <ConfirmDialog
 *     message="Discard unsaved changes?"
 *     onConfirm={blocker.retry}
 *     onCancel={blocker.reset}
 *   />
 * )}
 * ```
 *
 * Pass a boolean or a predicate. A predicate sees the pending `{ to, opts }`
 * so you can allow some destinations (e.g. don't block leaving to `/logout`).
 */
export declare const useBlocker: (shouldBlock: boolean | BlockerFn) => BlockerState;

/** Read the active fallback strings. Returns the English defaults when no
 *  provider is mounted, so the chrome works with zero setup. A per-component
 *  `strings` prop is deep-merged on top of whatever this returns. */
export declare const useFallbackStrings: (override?: PartialFallbackStrings) => FallbackStrings;

/**
 * Returns the loader data for the nearest level in the render tree: inside
 * a `layout.tsx` it's that layout's loader result; inside the page it's
 * the page loader's. Narrowed to the caller's type.
 *
 * When the loader used `defer()`, `LoaderData<T>` flattens the two buckets
 * into one object: eager fields as values, deferred fields as PROMISES to be
 * rendered through `<Await>`. For every other loader `LoaderData<T>` is `T`.
 */
export declare const useLoaderData: <T>() => LoaderData<T>;

export declare const useLocation: () => string;

export declare const useNavigate: () => RouterContextValue["navigate"];

/**
 * `useLoaderData()` for a component that may render at a level with no
 * `loader` — returns `undefined` there instead of throwing.
 *
 * This exists for ONE case, and it is worth stating so it is not reached for
 * casually: a component genuinely shared between routes that declare a loader
 * and routes that do not. On a page that declares its own `loader`, the router
 * never renders it without its data, so reaching for the optional read there
 * only hides a real mistake behind a `?.`.
 *
 * Note what it does NOT mean: an empty RESULT is a value, not an absence. A
 * loader returning `{ items: [] }` returns exactly that through both hooks —
 * `undefined` here says "there is no loader at this level", never "the query
 * found nothing".
 */
export declare const useOptionalLoaderData: <T>() => LoaderData<T> | undefined;

export declare const useParams: <T extends Record<string, string> = Record<string, string>>() => T;

/** Imperatively pre-warm a route's loader. No-op if the route has no loader. */
export declare const usePrefetch: () => ((to: string) => void);

export declare const useReconnect: () => (() => void);

/**
 * Read the request's URL search params as a standard `URLSearchParams`.
 *
 * Server-side (SSR / ISR) it parses the query off the request URL the
 * SSR pipeline captured — so a `renderMode: 'ssr'` page or layout can
 * read `?q=…` during `renderToString` with no client round-trip and
 * with the value already correct in the first paint. Client-side it
 * reads `window.location.search`. Both sides return the native
 * `URLSearchParams`, so call sites are identical:
 *
 * ```tsx
 * const params = useSearchParams()
 * const q = params.get('q') ?? ''
 * ```
 *
 * Resolves the params for the CURRENT render. SPA pages that must react
 * to router-pushed query changes without a reload should re-render via
 * the router (e.g. `useNavigate`/`useLocation`) — this hook then
 * re-resolves on that render.
 */
export declare const useSearchParams: () => URLSearchParams;

export declare const useServerRequest: () => ServerRequestContextValue | null;

/**
 * The WRITE half of `useSearchParams` — returns a setter that updates the
 * query string on the current pathname via the router's `navigate`
 * (`navigate` + rebuilt `?…`), so the URL changes AND every router-context
 * consumer re-renders immediately (same path that `withQuery` links take).
 *
 * ```tsx
 * const params = useSearchParams()          // read (SSR-aware)
 * const setParams = useSetSearchParams()     // write
 * setParams({ tab: 'skills' })               // → ?tab=skills (replace)
 * setParams((p) => { p.set('page', '2'); return p }, { push: true })
 * ```
 *
 * Defaults to a history REPLACE (a filter tweak shouldn't stack Back entries);
 * pass `{ push: true }` for a distinct history entry. Client-only — during SSR
 * there is no history to write, so read `useSearchParams()` off the request URL
 * instead and mutate on the client after hydration.
 */
export declare const useSetSearchParams: () => ((next: SearchParamsInit, opts?: SetSearchParamsOptions) => void);

/**
 * Read + set the app theme, backed by the SAME `voltro:theme` cookie and `.dark`
 * class the framework's pre-paint script uses.
 *
 * ```tsx
 * const { theme, resolvedTheme, setTheme } = useTheme()
 * <button onClick={() => setTheme(resolvedTheme === 'dark' ? 'light' : 'dark')}>
 * ```
 *
 * Requires `theme: 'system'` in the web `app.config.ts` (that's what emits the
 * pre-paint script). Do NOT also install a third-party theme provider — two
 * writers on one `class` attribute race on navigation.
 */
export declare const useTheme: () => ThemeState;

/** A URL minted by `externalUrl()` — anchored, hash, or cross-origin. */
export declare type VoltroExternalUrl = string & {
    readonly [EXTERNAL_URL_BRAND]: 'external';
};

/** A URL minted by the app's generated `routes` builder. */
export declare type VoltroRouteUrl = string & {
    readonly [ROUTE_URL_BRAND]: 'route';
};

export declare type VoltroUrl = VoltroRouteUrl | VoltroExternalUrl;

export declare const WEB_NAME: "framework-web";

/** Append a `#hash` to a route URL. Preserves the brand. */
export declare const withHash: (url: VoltroRouteUrl, hash: string) => VoltroRouteUrl;

/**
 * Append a query string to a route URL. Preserves the brand so the
 * result still flows through `<Link to=…>`. Pass `undefined` values
 * to omit a param entirely.
 *
 *   withQuery(routes['/_/p/[orgSlug]/[projectSlug]']({…}), { env: 'prod' })
 *   //→ '/_/p/acme/web?env=prod' (typed as VoltroRouteUrl)
 */
export declare const withQuery: (url: VoltroRouteUrl, params: Readonly<Record<string, string | number | undefined>>) => VoltroRouteUrl;


export * from "@voltro/client";
export * from "@voltro/ui";

export { }