@voltro/web 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1077 @@
+import { ComponentType } from 'react';
+import { Context } from 'react';
+import { ImgHTMLAttributes } from 'react';
+import { MouseEvent as MouseEvent_2 } from 'react';
+import { ReactElement } from 'react';
+import { ReactNode } from 'react';
+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>;
+
+/** 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;
+}
+
+/**
+ * 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 consumer overrides any subtree via
+ *  {@link FallbackStringsProvider} or a per-component `strings` prop;
+ *  unspecified keys fall through to these. */
+export declare const defaultFallbackStrings: FallbackStrings;
+
+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
+         *  `src/pages/` `<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';
+
+/**
+ * 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;
+
+/** 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, ...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 set, pre-warm the destination's loader on hover/focus. */
+    readonly prefetch?: boolean;
+    /** Swap the current history entry instead of pushing a new one —
+     *  mirror of `NavigateOptions.replace`. */
+    readonly replace?: boolean;
+}
+
+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;
+    /** Drop every entry. Test-only escape hatch. */
+    clear(): void;
+}
+
+export declare const loaderCacheKey: (pattern: string, params: Readonly<Record<string, string>>) => string;
+
+export declare interface LoaderContext {
+    readonly params: Readonly<Record<string, string>>;
+    readonly pathname: 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`. */
+    readonly query?: <T = unknown>(tag: string, input?: Record<string, unknown>) => Promise<T>;
+}
+
+/* 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> = (ctx: LoaderContext) => Promise<T> | T;
+
+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;
+
+/** 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 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>>;
+}
+
+export declare const pageRoute: (pattern: string, mod: Record<string, unknown>, extras?: {
+    readonly chain?: ReadonlyArray<RouteSegment>;
+}) => PageDescriptor;
+
+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?: boolean;
+}
+
+/**
+ * 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.
+ */
+export declare type RenderMode = 'static' | 'spa' | 'ssr' | 'isr';
+
+/**
+ * Auth headers for an api's WS rpc client. @effect/rpc sends these in the
+ * per-request MESSAGE frame (NOT the WS upgrade — a browser can't set upgrade
+ * headers), so the server's AuthMiddleware sees them on every call; this is
+ * what lets a cross-origin api authenticate WS subscriptions. A thunk is
+ * resolved fresh on every (re)connect, so a rotating token (e.g. a Supabase
+ * access token) is pulled anew per connect instead of freezing at first mount.
+ */
+declare type ResolvableHeaders = Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+
+/**
+ * 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 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;
+
+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 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.
+ */
+export declare const useLoaderData: <T>() => T;
+
+export declare const useLocation: () => string;
+
+export declare const useNavigate: () => RouterContextValue["navigate"];
+
+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);
+
+/** 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 { }