@rangojs/router 0.0.0-experimental.0b82333f

package/dist/cache/types.d.ts

@@ -0,0 +1,317 @@
+/**
+ * Cache Store Types
+ *
+ * Generic caching interface supporting multiple value types.
+ * Designed to be implemented by different backends:
+ * - MemoryCacheStore (dev/testing)
+ * - Cloudflare Cache API adapter
+ * - Cloudflare KV adapter
+ * - Redis adapter
+ */
+import type { ResolvedSegment } from "../types.js";
+import type { RequestContext } from "../server/request-context.js";
+/**
+ * Result from cache get() including data and revalidation status
+ */
+export interface CacheGetResult {
+    /** The cached entry data */
+    data: CachedEntryData;
+    /**
+     * Whether the caller should trigger background revalidation.
+     * True when entry is stale AND not already being revalidated.
+     * The store atomically marks the entry as REVALIDATING when returning true.
+     */
+    shouldRevalidate: boolean;
+}
+/**
+ * Low-level segment cache store interface.
+ *
+ * Implementations handle the actual storage (memory, KV, Redis, etc.).
+ * The store deals with serialized data - RSC serialization is handled
+ * by the cache provider layer.
+ *
+ * @typeParam TEnv - Platform bindings type (e.g., Cloudflare env)
+ */
+export interface SegmentCacheStore<TEnv = unknown> {
+    /**
+     * Default cache options for this store.
+     * Used by cache() boundaries when ttl/swr are not explicitly specified.
+     */
+    readonly defaults?: CacheDefaults;
+    /**
+     * Custom key generator applied to all cache operations using this store.
+     * Receives the full RequestContext and the default-generated key.
+     * Return value becomes the final cache key (unless route overrides with `key` option).
+     *
+     * Resolution priority:
+     * 1. Route-level `key` function (full override)
+     * 2. Store-level `keyGenerator` (modifies default key)
+     * 3. Default key generation (prefix:pathname:params)
+     *
+     * @example Using headers for cache segmentation
+     * ```typescript
+     * keyGenerator: (ctx, defaultKey) => {
+     *   const segment = ctx.request.headers.get('x-user-segment') || 'default';
+     *   return `${segment}:${defaultKey}`;
+     * }
+     * ```
+     *
+     * @example Using env bindings (Cloudflare)
+     * ```typescript
+     * keyGenerator: (ctx, defaultKey) => {
+     *   const region = ctx.env.REGION || 'us';
+     *   return `${region}:${defaultKey}`;
+     * }
+     * ```
+     *
+     * @example Using cookies for locale
+     * ```typescript
+     * keyGenerator: (ctx, defaultKey) => {
+     *   const locale = ctx.cookie('locale') || 'en';
+     *   return `${locale}:${defaultKey}`;
+     * }
+     * ```
+     */
+    readonly keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
+    /**
+     * Get cached entry data by key
+     * @returns Cache result with data and staleness, or null if not found/expired
+     */
+    get(key: string): Promise<CacheGetResult | null>;
+    /**
+     * Store entry data with TTL
+     * @param key - Cache key
+     * @param data - Serialized entry data
+     * @param ttl - Time-to-live in seconds
+     * @param swr - Optional stale-while-revalidate window in seconds
+     */
+    set(key: string, data: CachedEntryData, ttl: number, swr?: number): Promise<void>;
+    /**
+     * Delete a cached entry
+     * @returns true if deleted, false if not found
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Clear all cached entries (optional, for testing)
+     */
+    clear?(): Promise<void>;
+    /**
+     * Get a cached Response by key.
+     * Returns the response and whether it should be revalidated (SWR).
+     */
+    getResponse?(key: string): Promise<{
+        response: Response;
+        shouldRevalidate: boolean;
+    } | null>;
+    /**
+     * Store a Response with TTL and optional SWR window.
+     * @param key - Cache key
+     * @param response - Response to cache (will be cloned)
+     * @param ttl - Time-to-live in seconds
+     * @param swr - Optional stale-while-revalidate window in seconds
+     */
+    putResponse?(key: string, response: Response, ttl: number, swr?: number): Promise<void>;
+}
+/**
+ * Serialized segment data stored in cache
+ * Note: loading is preserved to ensure consistent tree structure between cached and fresh renders
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface SerializedSegmentData {
+    /** RSC-encoded component string */
+    encoded: string;
+    /** RSC-encoded layout string (if present) */
+    encodedLayout?: string;
+    /** RSC-encoded loading skeleton string (if present), or "null" for explicit null */
+    encodedLoading?: string;
+    /** RSC-encoded loaderData (if present) */
+    encodedLoaderData?: string;
+    /** RSC-encoded loaderDataPromise (if present) */
+    encodedLoaderDataPromise?: string;
+    /** Segment metadata (everything except component, layout, loading, and loader data) */
+    metadata: Omit<ResolvedSegment, "component" | "layout" | "loading" | "loaderData" | "loaderDataPromise">;
+}
+/**
+ * Raw data stored in cache for an entry
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface CachedEntryData {
+    /** Serialized segments for this entry */
+    segments: SerializedSegmentData[];
+    /** Handle data keyed by segment ID */
+    handles: Record<string, SegmentHandleData>;
+    /** Expiration timestamp (ms since epoch) */
+    expiresAt: number;
+}
+/**
+ * Default cache options applied to all cache() boundaries.
+ * Individual cache() calls can override any of these values.
+ *
+ * @example
+ * ```ts
+ * const store = new CFCacheStore({
+ *   defaults: { ttl: 60, swr: 300 }
+ * });
+ * ```
+ */
+export interface CacheDefaults {
+    /**
+     * Default time-to-live in seconds.
+     * After TTL expires, cached entry is considered stale.
+     */
+    ttl?: number;
+    /**
+     * Default stale-while-revalidate window in seconds.
+     * During SWR window, stale content is served while revalidating in background.
+     */
+    swr?: number;
+}
+/**
+ * Cache configuration for RSC handler
+ */
+export interface CacheConfig {
+    /** Cache store implementation (includes defaults) */
+    store: SegmentCacheStore;
+    /** Enable/disable caching (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Cache configuration - can be static or a function receiving env
+ */
+export type CacheConfigOrFactory<TEnv> = CacheConfig | ((env: TEnv) => CacheConfig);
+/**
+ * Handle data for a single segment
+ * Structure: { handleName: [values...] }
+ */
+export type SegmentHandleData = Record<string, unknown[]>;
+/**
+ * Result from cache get() including segments and their handle data
+ * Each entry can produce multiple segments (main + parallels)
+ */
+export interface CachedEntryResult {
+    /** All segments for this entry (main segment + parallels) */
+    segments: ResolvedSegment[];
+    /** Handle data keyed by segment ID */
+    handles: Record<string, SegmentHandleData>;
+}
+/**
+ * Segment cache provider interface
+ *
+ * Used by router to check/store segment cache during matching.
+ * Accessed via request context - if not present, caching is disabled.
+ *
+ * @internal Not currently implemented - CacheScope is used directly.
+ * Reserved for future extensibility.
+ */
+export interface SegmentCacheProvider {
+    /** Whether caching is enabled for this request */
+    readonly enabled: boolean;
+    /**
+     * Get cached segments and restore handles/loaders.
+     *
+     * Combines cache get with handle replay and loader data restoration.
+     * Returns tuple of [segments, segmentIds] if cache hit, null if miss or disabled.
+     *
+     * @param cacheKey - Cache key to look up
+     * @param params - Route params for cache key generation
+     * @param loaderPromises - Map to restore loader data into
+     * @returns Tuple of [segments, segmentIds] or null if miss
+     */
+    restore(cacheKey: string, params: Record<string, string>, loaderPromises: Map<string, Promise<any>>): Promise<[ResolvedSegment[], string[]] | null>;
+    /**
+     * Cache entry with automatic handle collection (non-blocking).
+     *
+     * Schedules caching via waitUntil - handles are collected after they settle.
+     * Validates segments have actual components before caching.
+     *
+     * @param cacheKey - The cache key to store under
+     * @param segments - All resolved segments for this entry
+     */
+    cacheEntry(cacheKey: string, segments: ResolvedSegment[]): void;
+}
+/**
+ * Supported cache value types for the generic CacheStore interface.
+ * @internal Reserved for future extensibility
+ */
+export type CacheValue = ReadableStream<Uint8Array> | Response | ArrayBuffer | string | unknown[] | Record<string, unknown>;
+/**
+ * Cache entry returned by match().
+ * @internal Reserved for future extensibility
+ */
+export interface CacheEntry<T = CacheValue> {
+    /** The cached value */
+    value: T;
+    /** Optional metadata stored with the entry */
+    metadata?: CacheMetadata;
+}
+/**
+ * Original value type for reconstruction.
+ * @internal Reserved for future extensibility
+ */
+export type CacheValueType = "stream" | "response" | "arraybuffer" | "string" | "object";
+/**
+ * Metadata associated with a cache entry.
+ * @internal Reserved for future extensibility
+ */
+export interface CacheMetadata {
+    /** Timestamp when entry expires (ms since epoch) */
+    expiresAt?: number;
+    /** Tags for bulk invalidation */
+    tags?: string[];
+    /** Original value type for reconstruction on read */
+    valueType?: CacheValueType;
+    /** Response headers (preserved when caching Response) */
+    responseHeaders?: Record<string, string>;
+    /** Response status (preserved when caching Response) */
+    responseStatus?: number;
+    /** Custom metadata */
+    [key: string]: unknown;
+}
+/**
+ * Options for put().
+ * @internal Reserved for future extensibility
+ */
+export interface CachePutOptions {
+    /** Time-to-live in seconds */
+    ttl?: number;
+    /** Metadata to store with entry */
+    metadata?: Omit<CacheMetadata, "expiresAt">;
+}
+/**
+ * Generic cache store interface for arbitrary value types.
+ *
+ * This interface is designed for future extensibility to support caching
+ * responses, streams, and other values. Currently, segment caching uses
+ * the SegmentCacheStore interface directly.
+ *
+ * Implementations must handle:
+ * - Stream values (clone before storing, streams can only be read once)
+ * - Promise values (await before storing)
+ * - Expiration/TTL
+ *
+ * @internal Reserved for future extensibility
+ */
+export interface CacheStore {
+    /**
+     * Retrieve a cached entry by key.
+     * @param key - Cache key
+     * @returns The cached entry or undefined if not found/expired
+     */
+    match<T = CacheValue>(key: string): Promise<CacheEntry<T> | undefined>;
+    /**
+     * Store a value in the cache.
+     * @param key - Cache key
+     * @param value - Value to cache (stream, response, string, object, etc.)
+     * @param options - TTL, metadata, etc.
+     */
+    put<T extends CacheValue>(key: string, value: T, options?: CachePutOptions): Promise<void>;
+    /**
+     * Delete a cached entry.
+     * @param key - Cache key
+     * @returns true if entry was deleted, false if not found
+     */
+    delete(key: string): Promise<boolean>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cache/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/cache/types.ts"],"names":[],"mappings":"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"}

package/dist/cache/types.js

@@ -0,0 +1,12 @@
+/**
+ * Cache Store Types
+ *
+ * Generic caching interface supporting multiple value types.
+ * Designed to be implemented by different backends:
+ * - MemoryCacheStore (dev/testing)
+ * - Cloudflare Cache API adapter
+ * - Cloudflare KV adapter
+ * - Redis adapter
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/cache/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/cache/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/client.d.ts

@@ -0,0 +1,248 @@
+import { Component, type ReactNode } from "react";
+import { type ClientErrorBoundaryFallbackProps, type LoaderDefinition, type LoaderFn, type ResolvedSegment } from "./types";
+/**
+ * Outlet component - renders child content in layouts
+ *
+ * If the current segment defines a loading component, the outlet content
+ * is wrapped in Suspense with the loading component as fallback.
+ * This means during navigation/streaming, React's Suspense will automatically
+ * show the loading skeleton until the content is ready.
+ *
+ * When a name prop is provided (e.g., "@modal"), renders content from
+ * the parallel segment with that slot name instead of the default content.
+ * This is used for parallel routes and intercepting routes.
+ *
+ * @param name - Optional slot name for parallel/intercept content (must start with @)
+ *
+ * @example
+ * ```tsx
+ * function BlogLayout() {
+ *   return (
+ *     <div>
+ *       <h1>Blog</h1>
+ *       <Outlet />
+ *     </div>
+ *   );
+ * }
+ *
+ * // With named slot for modal/parallel content:
+ * function KanbanLayout() {
+ *   return (
+ *     <div>
+ *       <KanbanBoard />
+ *       <Outlet name="@modal" />
+ *       <Outlet />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function Outlet({ name }?: {
+    name?: `@${string}`;
+}): ReactNode;
+/**
+ * ParallelOutlet component - renders content for a named parallel slot
+ *
+ * If the parallel segment defines a loading component, the content
+ * is wrapped in Suspense with the loading component as fallback.
+ * This enables streaming and navigation loading states for parallels.
+ *
+ * @param name - The slot name (must start with @, e.g., "@modal", "@sidebar")
+ *
+ * @example
+ * ```tsx
+ * function DashboardLayout() {
+ *   return (
+ *     <div>
+ *       <h1>Dashboard</h1>
+ *       <ParallelOutlet name="@sidebar" />
+ *       <ParallelOutlet name="@modal" />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function ParallelOutlet({ name }: {
+    name: `@${string}`;
+}): ReactNode;
+/**
+ * Provider for outlet content - used internally by renderSegments
+ *
+ * Stores a reference to parent context so useLoader can walk up the chain
+ * to find loader data from parent layouts. If this segment defines a loading
+ * component, Outlet will wrap content with Suspense using that as fallback.
+ */
+export declare function OutletProvider({ content, parallel, segment, loaderData, children, }: {
+    content: ReactNode;
+    parallel?: ResolvedSegment[];
+    segment?: ResolvedSegment;
+    loaderData?: Record<string, any>;
+    children: ReactNode;
+}): ReactNode;
+/**
+ * Hook to access outlet content programmatically
+ *
+ * Alternative to using <Outlet /> component. Useful when you need
+ * direct access to the outlet content in your logic.
+ *
+ * @example
+ * ```tsx
+ * function BlogLayout() {
+ *   const outlet = useOutlet();
+ *   return <div><h1>Blog</h1>{outlet}</div>;
+ * }
+ * ```
+ */
+export declare function useOutlet(): ReactNode;
+export { useLoader, useFetchLoader, type LoadFunction, type UseLoaderResult, type UseFetchLoaderResult, type UseLoaderOptions, } from "./use-loader.js";
+/**
+ * Hook to access all loader data in the current context
+ *
+ * Returns a record of all loader data available in the current outlet context
+ * and all parent contexts. Useful for debugging or when you need access to
+ * multiple loaders.
+ *
+ * @returns Record of loader name to data, or empty object if no loaders
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useLoaderData } from "rsc-router/client";
+ *
+ * export function DebugPanel() {
+ *   const loaderData = useLoaderData();
+ *   return <pre>{JSON.stringify(loaderData, null, 2)}</pre>;
+ * }
+ * ```
+ */
+export declare function useLoaderData(): Record<string, any>;
+/**
+ * Client-safe createLoader factory
+ *
+ * Creates a loader definition that can be used with useLoader().
+ * This is the client-side version that only stores the $$id - the function
+ * is ignored since loaders only execute on the server.
+ *
+ * The $$id is injected by the exposeLoaderId Vite plugin. In most cases,
+ * you should import the loader directly from the server file rather than
+ * creating a reference manually.
+ *
+ * @param fn - Loader function (ignored on client, kept for API compatibility)
+ * @param _fetchable - Optional fetchable flag (ignored on client)
+ * @param __injectedId - $$id injected by Vite plugin
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useLoader } from "rsc-router/client";
+ * import { CartLoader } from "../loaders/cart"; // Import from server file
+ *
+ * export function CartIcon() {
+ *   const cart = useLoader(CartLoader);
+ *   return <span>Cart ({cart?.items.length ?? 0})</span>;
+ * }
+ * ```
+ */
+export declare function createLoader<T>(fn: LoaderFn<T, Record<string, string | undefined>, any>): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+export declare function createLoader<T>(fn: LoaderFn<T, Record<string, string | undefined>, any>, fetchable: true): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+/**
+ * Props for the ErrorBoundary component
+ */
+export interface ErrorBoundaryProps {
+    /** Fallback UI to show when an error is caught */
+    fallback: ReactNode | ((props: ClientErrorBoundaryFallbackProps) => ReactNode);
+    /** Children to render */
+    children: ReactNode;
+    /** Optional callback when an error is caught */
+    onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * Client-side ErrorBoundary component
+ *
+ * Catches JavaScript errors in child components during rendering,
+ * in lifecycle methods, and in constructors of the whole tree below them.
+ * Displays a fallback UI instead of the component tree that crashed.
+ *
+ * Use this to wrap client components that might throw during hydration
+ * or user interaction. For server-side errors (middleware, loaders, handlers),
+ * use the errorBoundary() helper in route definitions instead.
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { ErrorBoundary } from "rsc-router/client";
+ *
+ * function MyComponent() {
+ *   return (
+ *     <ErrorBoundary fallback={<div>Something went wrong</div>}>
+ *       <ComponentThatMightThrow />
+ *     </ErrorBoundary>
+ *   );
+ * }
+ *
+ * // Or with a function fallback for more control:
+ * function MyComponent() {
+ *   return (
+ *     <ErrorBoundary
+ *       fallback={({ error, reset }) => (
+ *         <div>
+ *           <p>Error: {error.message}</p>
+ *           <button onClick={reset}>Try again</button>
+ *         </div>
+ *       )}
+ *     >
+ *       <ComponentThatMightThrow />
+ *     </ErrorBoundary>
+ *   );
+ * }
+ * ```
+ */
+export declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void;
+    reset: () => void;
+    render(): ReactNode;
+}
+export { useNavigation, type NavigationMethods, type NavigationValue, } from "./browser/react/use-navigation.js";
+export { useAction, type ServerActionFunction, } from "./browser/react/use-action.js";
+export { useSegments, type SegmentsState, } from "./browser/react/use-segments.js";
+export { useClientCache, type ClientCacheControls, } from "./browser/react/use-client-cache.js";
+export { NavigationProvider, type NavigationProviderProps, } from "./browser/react/NavigationProvider.js";
+export { Link, type LinkProps, type PrefetchStrategy, type StateOrGetter, } from "./browser/react/Link.js";
+export { useLinkStatus, type LinkStatus, } from "./browser/react/use-link-status.js";
+export { ScrollRestoration, useScrollRestoration, type ScrollRestorationProps, } from "./browser/react/ScrollRestoration.js";
+export { createHandle, isHandle, type Handle } from "./handle.js";
+export { useHandle } from "./browser/react/use-handle.js";
+export { Meta } from "./handles/meta.js";
+export { MetaTags } from "./handles/MetaTags.js";
+export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
+export { createLocationState, useLocationState, type LocationStateDefinition, type LocationStateEntry, } from "./browser/react/location-state.js";
+export { href, type ValidPaths, type PatternToPath, type PathResponse } from "./href-client.js";
+export type { ResponseEnvelope, ResponseError } from "./urls.js";
+/**
+ * Type guard for checking if a response envelope contains an error.
+ *
+ * @example
+ * ```typescript
+ * const result: ResponseEnvelope<Product> = await fetch(url).then(r => r.json());
+ * if (isResponseError(result)) {
+ *   console.log(result.error.message, result.error.code);
+ *   return;
+ * }
+ * result.data // fully typed as Product
+ * ```
+ */
+export declare function isResponseError<T>(result: import("./urls.js").ResponseEnvelope<T>): result is import("./urls.js").ResponseEnvelope<T> & {
+    error: import("./urls.js").ResponseError;
+};
+export { useMount } from "./browser/react/use-mount.js";
+export { MountContext } from "./browser/react/mount-context.js";
+export { useHref } from "./browser/react/use-href.js";
+export type { ScopedReverseFunction } from "./reverse.js";
+export type { LoaderDefinition } from "./types.js";
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.tsx"],"names":[],"mappings":"AAEA,OAAO,EACL,SAAS,EAKT,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,EACL,KAAK,gCAAgC,EAErC,KAAK,gBAAgB,EACrB,KAAK,QAAQ,EACb,KAAK,eAAe,EACrB,MAAM,SAAS,CAAC;AAMjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,MAAM,CAAC,EAAE,IAAI,EAAE,GAAE;IAAE,IAAI,CAAC,EAAE,IAAI,MAAM,EAAE,CAAA;CAAO,GAAG,SAAS,CA4FxE;AACD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,EAAE,IAAI,EAAE,EAAE;IAAE,IAAI,EAAE,IAAI,MAAM,EAAE,CAAA;CAAE,GAAG,SAAS,CA+E1E;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,EAC7B,OAAO,EACP,QAAQ,EACR,OAAO,EACP,UAAU,EACV,QAAQ,GACT,EAAE;IACD,OAAO,EAAE,SAAS,CAAC;IACnB,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,QAAQ,EAAE,SAAS,CAAC;CACrB,GAAG,SAAS,CAmBZ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,IAAI,SAAS,CAGrC;AAGD,OAAO,EACL,SAAS,EACT,cAAc,EACd,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAwBnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,EAAE,EAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EAAE,GAAG,CAAC,GACvD,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAGpE,wBAAgB,YAAY,CAAC,CAAC,EAC5B,EAAE,EAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EAAE,GAAG,CAAC,EACxD,SAAS,EAAE,IAAI,GACd,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAepE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,QAAQ,EACJ,SAAS,GACT,CAAC,CAAC,KAAK,EAAE,gCAAgC,KAAK,SAAS,CAAC,CAAC;IAC7D,yBAAyB;IACzB,QAAQ,EAAE,SAAS,CAAC;IACpB,gDAAgD;IAChD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,KAAK,IAAI,CAAC;CAC9D;AAED,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBAAa,aAAc,SAAQ,SAAS,CAC1C,kBAAkB,EAClB,kBAAkB,CACnB;gBACa,KAAK,EAAE,kBAAkB;IAKrC,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,KAAK,GAAG,kBAAkB;IAIjE,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,GAAG,IAAI;IAKjE,KAAK,QAAO,IAAI,CAEd;IAEF,MAAM,IAAI,SAAS;CAwBpB;AAQD,OAAO,EACL,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,eAAe,GACrB,MAAM,mCAAmC,CAAC;AAG3C,OAAO,EACL,SAAS,EACT,KAAK,oBAAoB,GAC1B,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EACL,WAAW,EACX,KAAK,aAAa,GACnB,MAAM,iCAAiC,CAAC;AAGzC,OAAO,EACL,cAAc,EACd,KAAK,mBAAmB,GACzB,MAAM,qCAAqC,CAAC;AAG7C,OAAO,EACL,kBAAkB,EAClB,KAAK,uBAAuB,GAC7B,MAAM,uCAAuC,CAAC;AAG/C,OAAO,EACL,IAAI,EACJ,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,aAAa,GACnB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,aAAa,EACb,KAAK,UAAU,GAChB,MAAM,oCAAoC,CAAC;AAG5C,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,sBAAsB,GAC5B,MAAM,sCAAsC,CAAC;AAG9C,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAGlE,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAG1D,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAG5E,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,GACxB,MAAM,mCAAmC,CAAC;AAG3C,OAAO,EAAE,IAAI,EAAE,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGhG,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAEjE;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,MAAM,EAAE,OAAO,WAAW,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAC9C,MAAM,IAAI,OAAO,WAAW,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG;IAAE,KAAK,EAAE,OAAO,WAAW,EAAE,aAAa,CAAA;CAAE,CAElG;AAGD,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAGhE,OAAO,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAGtD,YAAY,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAG1D,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}