@voltro/web 0.51.0 → 0.53.0

package/dist/index.d.ts

@@ -11,6 +11,7 @@ import { Ref } from 'react';
 import { ResolvableHeaders } from '@voltro/client';
 import { Rpc } from '@effect/rpc';
 import { RpcGroup } from '@effect/rpc';
+import { Schema } from 'effect';
 
 /** Decision outcome for a document-level anchor click. */
 export declare type AnchorNavigationDecision = {
@@ -167,6 +168,13 @@ declare interface CompiledRoute extends PageDescriptor {
 
 export declare const compileRoute: (route: PageDescriptor) => CompiledRoute;
 
+/**
+ * Decode a query string against a page's `searchParams` schema. Total: an
+ * invalid query yields the schema's defaults; only a schema that cannot even
+ * decode `{}` (a required field with no default) throws, naming the fix.
+ */
+export declare const decodeSearchParams: <A>(schema: SearchParamsSchema<A>, usp: URLSearchParams) => A;
+
 /** The English defaults. A deployment overrides any subtree via
  *  {@link FallbackStringsProvider} or a per-component `strings` prop;
  *  unspecified keys fall through to these. */
@@ -221,6 +229,18 @@ export declare interface DevStatus {
 
 export declare type DevStatusKind = 'compiling' | 'loading' | 'reconnecting' | 'error';
 
+/**
+ * Canonical link-side encode — the schema-free half. `routes.generated.ts`
+ * types a link's params through a TYPE-ONLY import; at runtime the values are
+ * serialised canonically: strings pass through, numbers/booleans via
+ * `String()`, arrays as repeated keys, `undefined` omitted. `Date` (or any
+ * object) is refused loudly: a link must encode to the exact string form the
+ * schema's decode side accepts, and there is no canonical Date string the type
+ * layer could guarantee — declare the field as a string/number transform
+ * instead.
+ */
+export declare const encodeSearchParams: (params: Readonly<Record<string, unknown>>) => URLSearchParams;
+
 export declare interface ErrorBoundaryProps {
     readonly error: unknown;
     readonly reset: () => void;
@@ -322,12 +342,20 @@ 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).
+ * markers and schedule each for hydration per its strategy. Called by the
+ * per-page islands entry, and by `@voltro/web/mount` when an islands page
+ * is reached through the full app bundle (SPA navigation). Idempotent —
+ * running twice is a no-op (we mark elements as visited).
  */
-export declare const hydrateIslandsOnPage: () => void;
+export declare const hydrateIslandsOnPage: (options?: HydrateIslandsOptions) => void;
+
+export declare interface HydrateIslandsOptions {
+    /** Wrap every island root — the per-page islands entry of a page whose
+     *  islands use framework hooks passes a `<VoltroRuntimeProvider>` here so
+     *  a `useSubscription` island gets a live runtime. Purely presentational
+     *  entries pass nothing and never load the client core. */
+    readonly wrap?: (children: ReactNode) => ReactNode;
+}
 
 export declare type HydrateStrategy = 
 /** Hydrate as soon as the client runtime mounts (after main script load). */
@@ -341,9 +369,14 @@ export declare type HydrateStrategy =
 | '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;
+| 'never'
+/** CLIENT-ONLY: the server renders an empty placeholder (never the
+*  component — a browser-only lib touching `window` in render would
+*  crash the SSR pass), and the client mounts fresh with `createRoot`
+*  instead of hydrating. Astro's `client:only`. */
+| 'only';
+
+declare const Image_2: ({ src, alt, width, height, fill, sizes, priority, loader, quality, placeholder, blurDataURL, style, ...rest }: ImageProps) => ReactElement;
 export { Image_2 as Image }
 
 /** App-level default loader for every `<Image>` below it. A per-image
@@ -355,14 +388,16 @@ export declare const ImageConfigProvider: ({ loader, children, }: {
 
 /** 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. */
+ *  against an image CDN or the storage serve endpoint. `quality` is set when
+ *  the `<Image quality>` prop is — forward it if your CDN supports it. */
 export declare type ImageLoader = (params: {
     readonly src: string;
     readonly width: number;
+    readonly quality?: number;
 }) => string;
 
 export declare interface ImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'width' | 'height' | 'loading' | 'srcSet'> {
-    readonly src: string;
+    readonly src: string | OptimizedImageAsset;
     /** Required — accessibility. Use `alt=""` for purely decorative images. */
     readonly alt: string;
     /** Intrinsic width in px. Required unless `fill`. */
@@ -379,7 +414,14 @@ export declare interface ImageProps extends Omit<ImgHTMLAttributes<HTMLImageElem
     readonly priority?: boolean;
     /** Per-image URL loader (overrides the ImageConfigProvider default). */
     readonly loader?: ImageLoader;
-    /** `'blur'` paints `blurDataURL` behind the image until it loads. */
+    /** Encode quality hint 1–100 forwarded to the URL loader (a hero wants 90,
+     *  a thumbnail 50). For a build-optimized `?image` asset the quality was
+     *  baked at build time (`images.quality` in app.config.ts) — this prop
+     *  applies to loader/CDN-resolved URLs. */
+    readonly quality?: number;
+    /** `'blur'` paints `blurDataURL` behind the image until it loads. A
+     *  build-optimized asset carries its own blur and defaults to `'blur'`;
+     *  pass `'empty'` to opt out. */
     readonly placeholder?: 'blur' | 'empty';
     readonly blurDataURL?: string;
 }
@@ -446,7 +488,7 @@ export declare const lazyPageRoute: (pattern: string, load: () => Promise<Record
     readonly chain?: ReadonlyArray<RouteSegment>;
 }) => PageDescriptor;
 
-export declare const Link: ({ to, children, onClick, prefetch: prefetchProp, replace, onMouseEnter, onFocus, ref, ...anchorProps }: LinkProps) => ReactNode;
+export declare const Link: ({ to, children, onClick, prefetch: prefetchProp, replace, transition, onMouseEnter, onFocus, ref, ...anchorProps }: LinkProps) => ReactNode;
 
 export declare interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href' | 'onClick'> {
     readonly to: VoltroUrl;
@@ -457,6 +499,11 @@ export declare interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLA
     /** Swap the current history entry instead of pushing a new one —
      *  mirror of `NavigateOptions.replace`. */
     readonly replace?: boolean;
+    /** Run this link's route swap through `document.startViewTransition`
+     *  (`true`) or force it off (`false`), overriding the app-wide
+     *  `router.viewTransitions` default — mirror of
+     *  `NavigateOptions.transition`. */
+    readonly transition?: boolean;
     /**
      * Forwarded to the underlying `<a>`.
      *
@@ -638,6 +685,21 @@ export declare type LoaderFn<T = unknown, Procedures = unknown> = (ctx: LoaderCo
  */
 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>;
 
+/**
+ * Reference a family declared in `app.config.ts` `fonts:`.
+ *
+ *   const inter = localFont('Inter')
+ *   <main style={{ fontFamily: inter.fontFamily }}>…</main>
+ */
+export declare const localFont: (family: string) => LocalFontHandle;
+
+export declare interface LocalFontHandle {
+    /** The CSS custom property the shell defines: `--font-<slug>`. */
+    readonly variable: string;
+    /** Ready-to-use `font-family` value: `var(--font-<slug>)`. */
+    readonly fontFamily: string;
+}
+
 /** 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`. */
@@ -707,6 +769,14 @@ export declare interface NavigateOptions {
     readonly replace?: boolean;
     /** Set to `false` to preserve the current scroll position. Defaults to true. */
     readonly scroll?: boolean;
+    /**
+     * Run this navigation's visual route swap through
+     * `document.startViewTransition` (`true`) or force it off (`false`),
+     * overriding the app-wide `router.viewTransitions` default for this one
+     * navigation. Browsers without the API and users with
+     * `prefers-reduced-motion: reduce` always get the plain swap regardless.
+     */
+    readonly transition?: boolean;
 }
 
 export declare const NavigationIndicator: () => ReactNode;
@@ -742,6 +812,31 @@ export declare class NotFoundError extends Error {
 
 export declare const noticeIslandsShipTheFullBundle: (isDev: boolean) => void;
 
+/**
+ * A build-optimized static asset — what a `?image` import resolves to:
+ *
+ *   import hero from './hero.jpg?image'
+ *   <Image src={hero} alt="…" />
+ *
+ * The CLI's sharp pipeline produced the variants at build time (on demand in
+ * dev); `<Image>` renders them as a `<picture>` with one `<source>` per
+ * modern format and infers width/height/blur — the CLS-required intrinsic
+ * size stops being a hand-written prop for imported assets.
+ */
+export declare interface OptimizedImageAsset {
+    readonly src: string;
+    readonly width: number;
+    readonly height: number;
+    readonly blurDataURL: string;
+    /** Fallback-format srcSet (jpeg/png). */
+    readonly srcSet: string;
+    /** Modern-format sources, in preference order (avif before webp). */
+    readonly sources: ReadonlyArray<{
+        readonly type: string;
+        readonly srcSet: string;
+    }>;
+}
+
 export declare const PAGE_SLOT_ATTR = "data-voltro-page-slot";
 
 export declare interface PageDescriptor<TLoaderData = unknown> {
@@ -794,6 +889,19 @@ export declare interface PageDescriptor<TLoaderData = unknown> {
      *  set this to `'islands'` so only marked interactive zones
      *  hydrate; the rest stays pure static HTML. */
     readonly interactive?: InteractiveMode | undefined;
+    /**
+     * Intercepting route (modal-with-URL): when a SOFT navigation reaches this
+     * page FROM one of the `from` route patterns, the page renders as an
+     * OVERLAY above the still-mounted origin page instead of replacing it —
+     * URL changes, Back closes the overlay, a hard load of the same URL
+     * renders the page standalone. `from` is one or more route PATTERNS
+     * (`'/photos'`, `'/albums/[id]'`); a soft navigation from any other route
+     * renders standalone. Full-hydration pages only (`interactive: 'full'`) —
+     * islands/none pages have no client router to intercept with.
+     */
+    readonly intercept?: {
+        readonly from: string | ReadonlyArray<string>;
+    } | undefined;
 }
 
 export declare interface PageMeta {
@@ -964,6 +1072,9 @@ export declare type RenderMode = (typeof RENDER_MODES)[number];
 
 /* Excluded from this release type: renderRouterProviderTree */
 
+/** Test seam. */
+export declare const resetScriptRegistryForTest: () => void;
+
 /**
  * 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
@@ -1005,7 +1116,7 @@ export declare interface RouteMatch {
     readonly params: Readonly<Record<string, string>>;
 }
 
-export declare const Router: ({ routes, notFounds, notFound: NotFound, errorFallback: ErrorFallback, }: RouterProps) => ReactNode;
+export declare const Router: ({ routes, notFounds, notFound: NotFound, errorFallback: ErrorFallback, viewTransitions, }: RouterProps) => ReactNode;
 
 /* Excluded from this release type: RouterContext */
 
@@ -1040,6 +1151,15 @@ export declare interface RouterProps {
     readonly notFound?: ComponentType;
     /** Fallback ErrorBoundary used when neither the leaf nor its chain supplies one. */
     readonly errorFallback?: ComponentType<ErrorBoundaryProps>;
+    /**
+     * Run SPA route swaps through `document.startViewTransition` — the browser
+     * cross-fades old and new page (customizable via `::view-transition-*` CSS).
+     * Set from `app.config.ts` `router.viewTransitions`; individual navigations
+     * override it via `navigate(to, { transition })` / `<Link transition>`.
+     * Browsers without the API and `prefers-reduced-motion: reduce` fall back to
+     * the exact untransitioned behavior.
+     */
+    readonly viewTransitions?: boolean;
 }
 
 /**
@@ -1081,10 +1201,55 @@ declare interface RouteSnapshot {
     readonly loaderData: unknown;
 }
 
+/**
+ * Declarative third-party script. Renders NOTHING into the HTML — the tag is
+ * injected client-side per `strategy`, deduplicated process-wide by `src`
+ * (external) or `id` (inline). Behavior per `interactive` mode is decided,
+ * not accidental: on an `interactive: 'none'` page the app bundle never runs,
+ * so a `<Script>` never fires (the build warns by name); on an islands page
+ * only `<Script>` INSIDE an island ever mounts — a `visible` island's script
+ * loads when the island hydrates (the build warns about `<Script>` in the
+ * static part).
+ */
+export declare const Script: ({ src, children, id, strategy, onLoad, onError, nonce, attributes, }: ScriptProps) => ReactElement | null;
+
+export declare interface ScriptProps {
+    /** External script URL. Exactly one of `src` / `children` is required. */
+    readonly src?: string;
+    /** Inline script body. Requires `id` (the dedupe key — inline code has no
+     *  src to key on). */
+    readonly children?: string;
+    /** Dedupe key for inline scripts; optional label for external ones. */
+    readonly id?: string;
+    /** `afterInteractive` (default): inject once this component mounts —
+     *  i.e. after hydration. `lazyOnload`: wait for browser idle. */
+    readonly strategy?: 'afterInteractive' | 'lazyOnload';
+    /** Fires when the script has executed — ALSO on a re-mount of the same
+     *  script, answered from the registry (the script itself is never
+     *  re-fetched or re-run). */
+    readonly onLoad?: () => void;
+    readonly onError?: (error: unknown) => void;
+    /** CSP nonce. Absent → the document's nonce is propagated when one exists. */
+    readonly nonce?: string;
+    /** Extra attributes for the tag (`data-*`, `crossorigin`, …). */
+    readonly attributes?: Readonly<Record<string, string>>;
+}
+
+declare const SEARCH_PARAMS_BRAND: unique symbol;
+
 /** 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>);
 
+/** A search-params schema: decodes a plain `Record<string, string | string[]>`
+ *  (the canonical URLSearchParams view) into the page's typed shape. */
+export declare type SearchParamsSchema<A> = Schema.Schema<A, any, never>;
+
+/** The canonical object view of a query string: repeated keys become arrays. */
+export declare const searchParamsToObject: (usp: URLSearchParams, opts?: {
+    readonly arrayKeys?: ReadonlySet<string>;
+}) => Record<string, string | ReadonlyArray<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
@@ -1155,23 +1320,6 @@ export declare interface ServerLogRelayOptions {
     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;
@@ -1337,10 +1485,27 @@ export declare const useReconnect: () => (() => void);
  * 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.
+ *
+ * Pass the page's own `searchParams` schema export to get the DECODED, typed
+ * shape instead (defaults applied; an invalid query falls back to the
+ * defaults — see `decodeSearchParams`). The schema value is module-local by
+ * design: the page imports its own export, so no generated module ever holds
+ * schema VALUES and links stay typed through type-only imports.
+ *
+ * ```tsx
+ * export const searchParams = Schema.Struct({
+ *   page: Schema.optionalWith(Schema.NumberFromString, { default: () => 1 }),
+ * })
+ * const { page } = useSearchParams(searchParams)   // number, SSR-aware
+ * ```
+ *
+ * Overload ORDER is load-bearing (the same rule `@voltro/client` pins): the
+ * schema overload must come after the zero-arg one, or every existing
+ * zero-arg call site would re-infer against the generic signature.
  */
-export declare const useSearchParams: () => URLSearchParams;
+export declare function useSearchParams(): URLSearchParams;
 
-export declare const useServerRequest: () => ServerRequestContextValue | null;
+export declare function useSearchParams<A>(schema: SearchParamsSchema<A>): A;
 
 /**
  * The WRITE half of `useSearchParams` — returns a setter that updates the
@@ -1359,8 +1524,25 @@ export declare const useServerRequest: () => ServerRequestContextValue | null;
  * 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.
+ *
+ * Pass the page's `searchParams` schema to get the TYPED setter. Its object
+ * form REPLACES the query — same semantics as the untyped form, an absent
+ * field decodes to its default on the next read — and its updater form
+ * receives the CURRENT decoded params, so a merge is an explicit spread:
+ *
+ * ```tsx
+ * const setParams = useSetSearchParams(searchParams)
+ * setParams({ page: 2 })                          // → ?page=2 (filter dropped)
+ * setParams((p) => ({ ...p, page: p.page + 1 }))  // keeps ?filter — typed merge
+ * ```
+ *
+ * Overload ORDER is load-bearing (same rule as `useSearchParams`): the schema
+ * overload comes after the zero-arg one, or every existing zero-arg call site
+ * would re-infer against the generic signature.
  */
-export declare const useSetSearchParams: () => ((next: SearchParamsInit, opts?: SetSearchParamsOptions) => void);
+export declare function useSetSearchParams(): (next: SearchParamsInit, opts?: SetSearchParamsOptions) => void;
+
+export declare function useSetSearchParams<A extends Readonly<Record<string, unknown>>>(schema: SearchParamsSchema<A>): (next: Partial<A> | ((current: A) => Partial<A>), opts?: SetSearchParamsOptions) => void;
 
 /**
  * Read + set the app theme, backed by the SAME `voltro:theme` cookie and `.dark`
@@ -1382,9 +1564,22 @@ 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 & {
+/**
+ * A URL minted by the app's generated `routes` builder.
+ *
+ * `TSearch` is a compile-time-only phantom: for a route whose page exports a
+ * `searchParams` schema, the codegen brands the builder's return as
+ * `VoltroRouteUrl<Schema.Schema.Type<typeof searchParams>>` through a
+ * TYPE-ONLY import — no schema value ever enters `routes.generated.ts`, so
+ * code-splitting stays intact — and `withQuery` then type-checks the params
+ * against the page's contract. The default is `unknown`, which every branded
+ * URL is assignable to, so a route without a schema (and every existing call
+ * site) is untouched.
+ */
+export declare type VoltroRouteUrl<TSearch = unknown> = string & {
     readonly [ROUTE_URL_BRAND]: 'route';
+} & {
+    readonly [SEARCH_PARAMS_BRAND]?: TSearch;
 };
 
 export declare type VoltroUrl = VoltroRouteUrl | VoltroExternalUrl;
@@ -1401,8 +1596,24 @@ export declare const withHash: (url: VoltroRouteUrl, hash: string) => VoltroRout
  *
  *   withQuery(routes['/_/p/[orgSlug]/[projectSlug]']({…}), { env: 'prod' })
  *   //→ '/_/p/acme/web?env=prod' (typed as VoltroRouteUrl)
+ *
+ * For a route whose page exports a `searchParams` schema, the URL carries the
+ * decoded shape as a phantom (see {@link VoltroRouteUrl}) and the params here
+ * type-check against it — a misspelt key or a wrong value type is a compile
+ * error. The ENCODE stays canonical and schema-free (strings pass through,
+ * number/boolean via String(), arrays as repeated keys) so the generated
+ * builder never needs the schema VALUE; the searchParams roundtrip test pins
+ * that this canonical form is exactly what the schema's decode accepts.
+ *
+ * ONE generic signature with a CONDITIONAL params type — deliberately not two
+ * overloads. With overloads, a wrong key on a typed URL fails the strict
+ * overload and silently falls through to the permissive one, so the compile
+ * error the phantom exists for never fires (the `.test-d.ts` pins exactly
+ * that). The conditional keeps one resolution path: a schema phantom infers
+ * `Partial<TSearch>`, the bare brand (phantom `unknown`) infers the free
+ * record.
  */
-export declare const withQuery: (url: VoltroRouteUrl, params: Readonly<Record<string, string | number | undefined>>) => VoltroRouteUrl;
+export declare function withQuery<TSearch = unknown>(url: VoltroRouteUrl<TSearch>, params: [TSearch] extends [Readonly<Record<string, unknown>>] ? Partial<TSearch> : Readonly<Record<string, string | number | boolean | ReadonlyArray<string | number | boolean> | undefined>>): VoltroRouteUrl<TSearch>;
 
 
 export * from "@voltro/client";