@emeryld/rrroutes-client 2.6.2 → 2.6.4

package/dist/sockets/socket.client.context.client.d.ts

@@ -0,0 +1,5 @@
+import type { EventMap, SocketConnectionConfigOutput } from '@emeryld/rrroutes-contract';
+import * as React from 'react';
+import { SocketClient } from './socket.client.core';
+export declare const SocketCtx: React.Context<SocketClient<any, SocketConnectionConfigOutput> | null>;
+export declare function useSocketClient<T extends EventMap, C extends SocketConnectionConfigOutput>(): SocketClient<T, C>;

package/dist/sockets/socket.client.context.connection.d.ts

@@ -0,0 +1,18 @@
+import type { EventMap, Payload, SocketConnectionConfigOutput, SocketSchemaOutput } from '@emeryld/rrroutes-contract';
+import type { ClientCtx, ServerEnvelope } from './socket.client.core';
+type Rooms = string[] | string | undefined;
+export type UseSocketConnectionArgs<T extends EventMap, K extends keyof T & string, C extends SocketConnectionConfigOutput> = {
+    event: K;
+    rooms?: Rooms;
+    onMessage: (payload: Payload<T, K>, meta?: {
+        envelope: ServerEnvelope<T, K>;
+        ctx: ClientCtx;
+    }) => void;
+    onCleanup?: () => void;
+    autoJoin?: boolean;
+    autoLeave?: boolean;
+    joinMeta: SocketSchemaOutput<C['joinMetaMessage']>;
+    leaveMeta: SocketSchemaOutput<C['leaveMetaMessage']>;
+};
+export declare function useSocketConnection<T extends EventMap, K extends keyof T & string, C extends SocketConnectionConfigOutput>(args: UseSocketConnectionArgs<T, K, C>): void;
+export {};

package/dist/sockets/socket.client.context.d.ts

@@ -1,71 +1,4 @@
-import { EventMap, Payload, SocketConnectionConfigOutput, SocketSchemaOutput } from '@emeryld/rrroutes-contract';
-import * as React from 'react';
-import { Socket } from 'socket.io-client';
-import { ClientCtx, ServerEnvelope, SocketClient, SocketClientOptions } from './socket.client.index';
-/** === Provider-side debug === */
-type HookDebugReason = 'init' | 'change';
-type HookDebugValue = string | number | boolean | null | undefined;
-export type SocketProviderDebugEvent = {
-    type: 'resolve';
-    phase: 'start' | 'ok' | 'error' | 'socketMissing' | 'cancelled';
-    err?: string;
-} | {
-    type: 'client';
-    phase: 'init' | 'destroy';
-    missing?: boolean;
-} | {
-    type: 'render';
-    hasClient: boolean;
-} | {
-    type: 'hook';
-    phase: 'resolve_effect' | 'client_memo' | 'destroy_effect';
-    reason: HookDebugReason;
-    changes: Array<{
-        dependency: string;
-        previous: HookDebugValue;
-        next: HookDebugValue;
-    }>;
-};
-export type SocketProviderDebugOptions = {
-    verbose?: boolean;
-    logger?: (e: SocketProviderDebugEvent) => void;
-} & {
-    [P in SocketProviderDebugEvent['type']]?: boolean;
-};
-/** === Types for runtime socket injection === */
-type BaseOptions<T extends EventMap, C extends SocketConnectionConfigOutput> = Omit<SocketClientOptions<T, C>, 'socket'>;
-type ProviderRuntimeSocket = {
-    socket: Socket | null;
-} | {
-    getSocket: () => Socket | Promise<Socket>;
-};
-export declare function buildSocketProvider<T extends EventMap, C extends SocketConnectionConfigOutput>(args: {
-    events: T;
-    options: Omit<BaseOptions<T, C>, 'debug'> & {
-        debug: BaseOptions<T, C>['debug'] & SocketProviderDebugOptions;
-    };
-}): {
-    SocketProvider: (props: React.PropsWithChildren<ProviderRuntimeSocket & {
-        fallback?: React.ReactNode;
-        destroyLeaveMeta: SocketSchemaOutput<C["leaveMetaMessage"]>;
-    }>) => import("react/jsx-runtime").JSX.Element;
-    useSocketClient: () => SocketClient<T, C>;
-    useSocketConnection: <K extends keyof T & string>(p: Parameters<typeof useSocketConnection<T, K, C>>[0]) => void;
-};
-export declare function useSocketClient<T extends EventMap, C extends SocketConnectionConfigOutput>(): SocketClient<T, C>;
-type Rooms = string[] | string | undefined;
-export type UseSocketConnectionArgs<T extends EventMap, K extends keyof T & string, C extends SocketConnectionConfigOutput> = {
-    event: K;
-    rooms?: Rooms;
-    onMessage: (payload: Payload<T, K>, meta?: {
-        envelope: ServerEnvelope<T, K>;
-        ctx: ClientCtx;
-    }) => void;
-    onCleanup?: () => void;
-    autoJoin?: boolean;
-    autoLeave?: boolean;
-    joinMeta: SocketSchemaOutput<C['joinMetaMessage']>;
-    leaveMeta: SocketSchemaOutput<C['leaveMetaMessage']>;
-};
-export declare function useSocketConnection<T extends EventMap, K extends keyof T & string, C extends SocketConnectionConfigOutput>(args: UseSocketConnectionArgs<T, K, C>): void;
-export {};
+export { buildSocketProvider } from './socket.client.context.provider';
+export { useSocketClient } from './socket.client.context.client';
+export { useSocketConnection, type UseSocketConnectionArgs, } from './socket.client.context.connection';
+export type { SocketProviderDebugEvent, SocketProviderDebugOptions, } from './socket.client.context.debug';

package/dist/sockets/socket.client.context.debug.d.ts

@@ -0,0 +1,50 @@
+import type * as React from 'react';
+type HookDebugReason = 'init' | 'change';
+type HookDebugValue = string | number | boolean | null | undefined;
+export type SocketProviderDebugEvent = {
+    type: 'resolve';
+    phase: 'start' | 'ok' | 'error' | 'socketMissing' | 'cancelled';
+    err?: string;
+} | {
+    type: 'client';
+    phase: 'init' | 'destroy';
+    missing?: boolean;
+} | {
+    type: 'render';
+    hasClient: boolean;
+} | {
+    type: 'hook';
+    phase: 'resolve_effect' | 'client_memo' | 'destroy_effect';
+    reason: HookDebugReason;
+    changes: Array<{
+        dependency: string;
+        previous: HookDebugValue;
+        next: HookDebugValue;
+    }>;
+};
+export type SocketProviderDebugOptions = {
+    verbose?: boolean;
+    logger?: (e: SocketProviderDebugEvent) => void;
+} & {
+    [P in SocketProviderDebugEvent['type']]?: boolean;
+};
+export type HookDebugSnapshot = Record<string, unknown>;
+type HookIdentifier = Extract<SocketProviderDebugEvent, {
+    type: 'hook';
+}>['phase'];
+export declare function dbg(dbgOpts: SocketProviderDebugOptions | undefined, e: SocketProviderDebugEvent): void;
+export declare function describeSocketLike(value: {
+    id?: string;
+    connected?: boolean;
+    recovered?: boolean;
+} | null): HookDebugValue;
+export declare function summarizeEvents(events: unknown): HookDebugValue;
+export declare function summarizeBaseOptions(options: unknown): HookDebugValue;
+export declare function summarizeMeta(meta: unknown, label: string): HookDebugValue;
+export declare function trackHookTrigger({ ref, hook, providerDebug, snapshot, }: {
+    ref: React.MutableRefObject<HookDebugSnapshot | null>;
+    hook: HookIdentifier;
+    providerDebug?: SocketProviderDebugOptions;
+    snapshot: HookDebugSnapshot;
+}): void;
+export {};

package/dist/sockets/socket.client.context.provider.d.ts

@@ -0,0 +1,26 @@
+import type { EventMap, SocketConnectionConfigOutput, SocketSchemaOutput } from '@emeryld/rrroutes-contract';
+import * as React from 'react';
+import type { Socket } from 'socket.io-client';
+import { SocketClient, type SocketClientOptions } from './socket.client.core';
+import { type UseSocketConnectionArgs } from './socket.client.context.connection';
+import { SocketProviderDebugOptions } from './socket.client.context.debug';
+type BaseOptions<T extends EventMap, C extends SocketConnectionConfigOutput> = Omit<SocketClientOptions<T, C>, 'socket'>;
+type ProviderRuntimeSocket = {
+    socket: Socket | null;
+} | {
+    getSocket: () => Socket | Promise<Socket>;
+};
+export declare function buildSocketProvider<T extends EventMap, C extends SocketConnectionConfigOutput>(args: {
+    events: T;
+    options: Omit<BaseOptions<T, C>, 'debug'> & {
+        debug: BaseOptions<T, C>['debug'] & SocketProviderDebugOptions;
+    };
+}): {
+    SocketProvider: (props: React.PropsWithChildren<ProviderRuntimeSocket & {
+        fallback?: React.ReactNode;
+        destroyLeaveMeta: SocketSchemaOutput<C["leaveMetaMessage"]>;
+    }>) => import("react/jsx-runtime").JSX.Element;
+    useSocketClient: () => SocketClient<T, C>;
+    useSocketConnection: <K extends keyof T & string>(p: UseSocketConnectionArgs<T, K, C>) => void;
+};
+export {};

package/dist/sockets/socket.client.core.d.ts

@@ -0,0 +1,116 @@
+import type { EventMap, Payload, SocketConnectionConfigOutput, SocketSchemaOutput } from '@emeryld/rrroutes-contract';
+import { SocketClientDebugEvent } from './socket.client.debug';
+import type { MaybeSocket, SysEventMap } from './socket.client.sys';
+export type ServerEnvelope<T extends EventMap, K extends keyof T & string> = {
+    eventName: K;
+    sentAt: string | Date;
+    sentTo: string[];
+    data?: Payload<T, K>;
+    metadata?: Record<string, unknown>;
+    rooms: string[];
+};
+export type ClientCtx = {
+    receivedAt: Date;
+    latencyMs?: number;
+    nsp?: string;
+    socketId?: string;
+    socket?: MaybeSocket;
+    reply?: (data?: unknown) => void;
+};
+export type ClientStatsSnapshot = {
+    roomsCount: number;
+    totalHandlers: number;
+    rooms: {
+        room: string;
+        count: number;
+    }[];
+    handlers: {
+        event: string;
+        handlers: number;
+    }[];
+};
+export type SocketClientDebugOptions<K extends string = string> = {
+    verbose?: boolean;
+    only?: K[];
+    logger?: (e: SocketClientDebugEvent<K>) => void;
+} & {
+    [P in SocketClientDebugEvent['type']]?: boolean;
+};
+/** === Heartbeat config (now only timing + optional onPong) === */
+export type HeartbeatClientOptions = {
+    /** Interval between pings. Default 15_000. */
+    intervalMs?: number;
+    /** Give up waiting for pong after this many ms. Default 7_500. */
+    timeoutMs?: number;
+};
+export type SocketClientOptions<T extends EventMap = EventMap, C extends SocketConnectionConfigOutput = SocketConnectionConfigOutput> = {
+    /** Inject an existing socket.io-client Socket. Can be null while bootstrapping. */
+    socket: MaybeSocket;
+    config: C;
+    environment?: 'development' | 'production';
+    debug?: SocketClientDebugOptions<keyof T & string>;
+    heartbeat?: HeartbeatClientOptions;
+    sys: SysEventMap<T, C>;
+};
+export declare class SocketClient<T extends EventMap, C extends SocketConnectionConfigOutput = SocketConnectionConfigOutput> {
+    readonly socket: MaybeSocket;
+    private readonly events;
+    private readonly environment;
+    private readonly debug;
+    private readonly config;
+    private readonly sysEvents;
+    private readonly roomJoinSchema;
+    private readonly roomLeaveSchema;
+    private readonly hb;
+    private hbTimer;
+    /** keep references so we can .off() later */
+    private readonly onConnect;
+    private readonly onReconnect;
+    private readonly onDisconnect;
+    private readonly onConnectError;
+    private readonly onPong;
+    private readonly roomCounts;
+    private readonly handlerMap;
+    private snapshotSocketConfig;
+    private logSocketConfigSnapshot;
+    private getValidationDetails;
+    private getVerboseDetails;
+    private getNamespace;
+    constructor(events: T, opts: SocketClientOptions<T, C>);
+    private getSysEvent;
+    private dbg;
+    /** internal stats snapshot */
+    stats(): ClientStatsSnapshot;
+    private toArray;
+    private rollbackJoinIncrement;
+    private rollbackLeaveDecrement;
+    /**
+     * Public: start the heartbeat loop manually.
+     *
+     * This is called by the default 'sys:connect' handler, but you can also
+     * call it yourself from any sysHandler to change when heartbeats start.
+     */
+    startHeartbeat(): void;
+    /**
+     * Public: stop the heartbeat loop.
+     *
+     * This is called by the default 'sys:disconnect' handler, but you can also
+     * call it yourself from any sysHandler to fully control heartbeat lifecycle.
+     */
+    stopHeartbeat(reason?: string): void;
+    emit<K extends keyof T & string>(event: K, payload: Payload<T, K>, metadata?: Record<string, unknown>): void;
+    joinRooms(rooms: string[] | string, meta: SocketSchemaOutput<C['joinMetaMessage']>): Promise<() => Promise<void>>;
+    leaveRooms(rooms: string[] | string, meta: SocketSchemaOutput<C['leaveMetaMessage']>): Promise<void>;
+    on<K extends keyof T & string>(event: K, handler: (payload: Payload<T, K>, meta?: {
+        envelope: ServerEnvelope<T, K>;
+        ctx: ClientCtx;
+    }) => void): () => void;
+    /**
+     * Remove all listeners, stop timers, and leave rooms.
+     * Call when disposing the client instance.
+     */
+    destroy(leaveMeta: SocketSchemaOutput<C['leaveMetaMessage']>): Promise<void>;
+    /** Pass-throughs. Managing connection is the caller’s responsibility. */
+    disconnect(): void;
+    connect(): void;
+}

package/dist/sockets/socket.client.index.d.ts

@@ -1,119 +1,4 @@
-import type { EventMap, Payload, SocketConnectionConfigOutput, SocketSchemaOutput } from '@emeryld/rrroutes-contract';
-import { SocketClientDebugEvent } from './socket.client.debug';
-import type { MaybeSocket, SysEventMap } from './socket.client.sys';
-export type ServerEnvelope<T extends EventMap, K extends keyof T & string> = {
-    eventName: K;
-    sentAt: string | Date;
-    sentTo: string[];
-    data?: Payload<T, K>;
-    metadata?: Record<string, unknown>;
-    rooms: string[];
-};
-export type ClientCtx = {
-    receivedAt: Date;
-    latencyMs?: number;
-    nsp?: string;
-    socketId?: string;
-    socket?: MaybeSocket;
-    reply?: (data?: unknown) => void;
-};
-export type ClientStatsSnapshot = {
-    roomsCount: number;
-    totalHandlers: number;
-    rooms: {
-        room: string;
-        count: number;
-    }[];
-    handlers: {
-        event: string;
-        handlers: number;
-    }[];
-};
-export type SocketClientDebugOptions<K extends string = string> = {
-    verbose?: boolean;
-    only?: K[];
-    logger?: (e: SocketClientDebugEvent<K>) => void;
-} & {
-    [P in SocketClientDebugEvent['type']]?: boolean;
-};
-/** === Heartbeat config (now only timing + optional onPong) === */
-export type HeartbeatClientOptions = {
-    /** Interval between pings. Default 15_000. */
-    intervalMs?: number;
-    /** Give up waiting for pong after this many ms. Default 7_500. */
-    timeoutMs?: number;
-};
-export type SocketClientOptions<T extends EventMap = EventMap, C extends SocketConnectionConfigOutput = SocketConnectionConfigOutput> = {
-    /** Inject an existing socket.io-client Socket. Can be null while bootstrapping. */
-    socket: MaybeSocket;
-    config: C;
-    environment?: 'development' | 'production';
-    debug?: SocketClientDebugOptions<keyof T & string>;
-    heartbeat?: HeartbeatClientOptions;
-    sys: SysEventMap<T, C>;
-};
-export declare class SocketClient<T extends EventMap, C extends SocketConnectionConfigOutput = SocketConnectionConfigOutput> {
-    readonly socket: MaybeSocket;
-    private readonly events;
-    private readonly environment;
-    private readonly debug;
-    private readonly config;
-    private readonly sysEvents;
-    private readonly roomJoinSchema;
-    private readonly roomLeaveSchema;
-    private readonly hb;
-    private hbTimer;
-    /** keep references so we can .off() later */
-    private readonly onConnect;
-    private readonly onReconnect;
-    private readonly onDisconnect;
-    private readonly onConnectError;
-    private readonly onPong;
-    private readonly roomCounts;
-    private readonly handlerMap;
-    private snapshotSocketConfig;
-    private logSocketConfigSnapshot;
-    private getValidationDetails;
-    private getVerboseDetails;
-    private getNamespace;
-    constructor(events: T, opts: SocketClientOptions<T, C>);
-    private getSysEvent;
-    private dbg;
-    /** internal stats snapshot */
-    stats(): ClientStatsSnapshot;
-    private toArray;
-    private rollbackJoinIncrement;
-    private rollbackLeaveDecrement;
-    /**
-     * Public: start the heartbeat loop manually.
-     *
-     * This is called by the default 'sys:connect' handler, but you can also
-     * call it yourself from any sysHandler to change when heartbeats start.
-     */
-    startHeartbeat(): void;
-    /**
-     * Public: stop the heartbeat loop.
-     *
-     * This is called by the default 'sys:disconnect' handler, but you can also
-     * call it yourself from any sysHandler to fully control heartbeat lifecycle.
-     */
-    stopHeartbeat(reason?: string): void;
-    emit<K extends keyof T & string>(event: K, payload: Payload<T, K>, metadata?: Record<string, unknown>): void;
-    joinRooms(rooms: string[] | string, meta: SocketSchemaOutput<C['joinMetaMessage']>): Promise<() => Promise<void>>;
-    leaveRooms(rooms: string[] | string, meta: SocketSchemaOutput<C['leaveMetaMessage']>): Promise<void>;
-    on<K extends keyof T & string>(event: K, handler: (payload: Payload<T, K>, meta?: {
-        envelope: ServerEnvelope<T, K>;
-        ctx: ClientCtx;
-    }) => void): () => void;
-    /**
-     * Remove all listeners, stop timers, and leave rooms.
-     * Call when disposing the client instance.
-     */
-    destroy(leaveMeta: SocketSchemaOutput<C['leaveMetaMessage']>): Promise<void>;
-    /** Pass-throughs. Managing connection is the caller’s responsibility. */
-    disconnect(): void;
-    connect(): void;
-}
+export * from './socket.client.core';
 export * from './socket.client.context';
 export * from './socket.client.sys';
 export * from './socketedRoute/socket.client.helper';

package/dist/sockets/socket.client.sys.d.ts

@@ -1,7 +1,7 @@
 import type { Socket } from 'socket.io-client';
 import { z } from 'zod';
 import type { EventMap, SocketConnectionConfigOutput, SocketSchemaOutput } from '@emeryld/rrroutes-contract';
-import { SocketClient } from './socket.client.index';
+import type { SocketClient } from './socket.client.core';
 export type MaybeSocket = Socket | null;
 export type SysEventMap<T extends EventMap, C extends SocketConnectionConfigOutput = SocketConnectionConfigOutput> = {
     'sys:connect': (args: {

package/dist/sockets/socketedRoute/socket.client.helper.d.ts

@@ -1,70 +1,2 @@
-import type { AnyLeafLowProfile, EventMap, InferOutput, Payload, SocketConnectionConfigOutput, SocketSchemaOutput } from '@emeryld/rrroutes-contract';
-import type { BuiltInfinite, BuiltQuery, DataShape, InfiniteUseEndpointResultFor, QueryUseEndpointResultFor, UseEndpointArgs } from '../../routesV3.client.types';
-import type { ClientCtx, ServerEnvelope, SocketClient } from '../socket.client.index';
-type RoomsInput = string | string[] | undefined | null;
-type HookDebugReason = 'init' | 'change';
-type HookDebugValue = string | number | boolean | null | undefined;
-export type SocketedRouteDebugEvent = {
-    type: 'client';
-    phase: 'ready' | 'missing';
-    err?: string;
-} | {
-    type: 'render';
-    renderCount: number;
-    hasClient: boolean;
-    argsKey: string;
-    rooms: string[];
-    roomsKey: string;
-    joinMetaKey: string;
-    leaveMetaKey: string;
-} | {
-    type: 'hook';
-    phase: 'endpoint_on_receive_effect' | 'derive_rooms_effect' | 'join_rooms_effect' | 'apply_socket_effect';
-    reason: HookDebugReason;
-    changes: Array<{
-        dependency: string;
-        previous: HookDebugValue;
-        next: HookDebugValue;
-    }>;
-} | {
-    type: 'room';
-    phase: 'join_attempt' | 'join_skip' | 'join_error' | 'leave_attempt' | 'leave_skip' | 'leave_error';
-    rooms: string[];
-    reason?: string;
-    err?: string;
-};
-export type SocketedRouteDebugOptions = {
-    logger?: (event: SocketedRouteDebugEvent) => void;
-} & {
-    [P in SocketedRouteDebugEvent['type']]?: boolean;
-};
-type SocketedBuilt<L extends AnyLeafLowProfile> = L['cfg']['feed'] extends true ? BuiltInfinite<L> : BuiltQuery<L>;
-type SocketedRouteResult<L extends AnyLeafLowProfile> = (L['cfg']['feed'] extends true ? InfiniteUseEndpointResultFor<L> : QueryUseEndpointResultFor<L>) & {
-    rooms: string[];
-};
-export type SocketedRouteOptions<L extends AnyLeafLowProfile, Events extends EventMap, C extends SocketConnectionConfigOutput> = {
-    built: SocketedBuilt<L>;
-    toRooms: (data: InferOutput<L>) => {
-        rooms: RoomsInput;
-        joinMeta: SocketSchemaOutput<C['joinMetaMessage']>;
-        leaveMeta: SocketSchemaOutput<C['leaveMetaMessage']>;
-    };
-    applySocket: {
-        [K in keyof Events & string]?: (prev: DataShape<L> | undefined, payload: Payload<Events, K>, meta: {
-            envelope?: ServerEnvelope<Events, keyof Events & string>;
-            ctx?: ClientCtx;
-            args: UseEndpointArgs<L>;
-        }) => DataShape<L> | undefined;
-    };
-    useSocketClient: () => SocketClient<Events, C>;
-    debug?: SocketedRouteDebugOptions;
-};
-/**
- * Compose a GET endpoint with socket wiring:
- * - joins/leaves rooms derived from the endpoint data
- * - subscribes to a socket event and applies messages to the cache
- */
-export declare function buildSocketedRoute<L extends AnyLeafLowProfile, Events extends EventMap, C extends SocketConnectionConfigOutput>(options: SocketedRouteOptions<L, Events, C>): Omit<SocketedBuilt<L>, "useEndpoint"> & {
-    useEndpoint: (...useArgs: UseEndpointArgs<L>) => SocketedRouteResult<L>;
-};
-export {};
+export type { SocketedRouteDebugEvent, SocketedRouteDebugOptions, } from './socket.client.helper.debug';
+export { buildSocketedRoute, type SocketedRouteOptions, } from './socket.client.helper.route';

package/dist/sockets/socketedRoute/socket.client.helper.debug.d.ts

@@ -0,0 +1,54 @@
+export type HookDebugReason = 'init' | 'change';
+export type HookDebugValue = string | number | boolean | null | undefined;
+export type SocketedRouteDebugEvent = {
+    type: 'client';
+    phase: 'ready' | 'missing';
+    err?: string;
+} | {
+    type: 'render';
+    renderCount: number;
+    hasClient: boolean;
+    argsKey: string;
+    rooms: string[];
+    roomsKey: string;
+    joinMetaKey: string;
+    leaveMetaKey: string;
+} | {
+    type: 'hook';
+    phase: 'endpoint_on_receive_effect' | 'derive_rooms_effect' | 'join_rooms_effect' | 'apply_socket_effect';
+    reason: HookDebugReason;
+    changes: Array<{
+        dependency: string;
+        previous: HookDebugValue;
+        next: HookDebugValue;
+    }>;
+} | {
+    type: 'room';
+    phase: 'join_attempt' | 'join_skip' | 'join_error' | 'leave_attempt' | 'leave_skip' | 'leave_error';
+    rooms: string[];
+    reason?: string;
+    err?: string;
+};
+export type SocketedRouteDebugOptions = {
+    logger?: (event: SocketedRouteDebugEvent) => void;
+} & {
+    [P in SocketedRouteDebugEvent['type']]?: boolean;
+};
+export type HookDebugSnapshot = Record<string, unknown>;
+type HookIdentifier = Extract<SocketedRouteDebugEvent, {
+    type: 'hook';
+}>['phase'];
+export declare function describeObjectReference(value: unknown): string | null;
+export declare function safeJsonKey(value: unknown): string;
+export declare function isSameObjectReference(prev: unknown, next: unknown): boolean;
+export declare function shouldWarnSocketMutationGuard(): boolean;
+export declare function dbg(debug: SocketedRouteDebugOptions | undefined, event: SocketedRouteDebugEvent): void;
+export declare function trackHookTrigger({ ref, phase, debug, snapshot, }: {
+    ref: {
+        current: HookDebugSnapshot | null;
+    };
+    phase: HookIdentifier;
+    debug?: SocketedRouteDebugOptions;
+    snapshot: HookDebugSnapshot;
+}): void;
+export {};

package/dist/sockets/socketedRoute/socket.client.helper.rooms.d.ts

@@ -0,0 +1,17 @@
+import type { AnyLeafLowProfile, InferOutput, SocketConnectionConfigOutput, SocketSchemaOutput } from '@emeryld/rrroutes-contract';
+import type { DataShape } from '../../routesV3.client.types';
+export type RoomsInput = string | string[] | undefined | null;
+export type RoomState<C extends SocketConnectionConfigOutput> = {
+    rooms: string[];
+    joinMeta?: SocketSchemaOutput<C['joinMetaMessage']>;
+    leaveMeta?: SocketSchemaOutput<C['leaveMetaMessage']>;
+};
+export type ToRoomsResult<C extends SocketConnectionConfigOutput> = {
+    rooms: RoomsInput;
+    joinMeta: SocketSchemaOutput<C['joinMetaMessage']>;
+    leaveMeta: SocketSchemaOutput<C['leaveMetaMessage']>;
+};
+export type ToRoomsMapper<L extends AnyLeafLowProfile, C extends SocketConnectionConfigOutput> = (data: InferOutput<L>) => ToRoomsResult<C>;
+export declare function roomStateEqual<C extends SocketConnectionConfigOutput>(prev: RoomState<C>, next: RoomState<C>): boolean;
+export declare function mergeRoomState<L extends AnyLeafLowProfile, C extends SocketConnectionConfigOutput>(prev: RoomState<C>, toRoomsResult: ToRoomsResult<C>): RoomState<C>;
+export declare function roomsFromData<L extends AnyLeafLowProfile, C extends SocketConnectionConfigOutput>(data: DataShape<L> | undefined, toRooms: ToRoomsMapper<L, C>): RoomState<C>;

package/dist/sockets/socketedRoute/socket.client.helper.route.d.ts

@@ -0,0 +1,31 @@
+import type { AnyLeafLowProfile, EventMap, Payload, SocketConnectionConfigOutput } from '@emeryld/rrroutes-contract';
+import type { BuiltInfinite, BuiltQuery, DataShape, InfiniteUseEndpointResultFor, QueryUseEndpointResultFor, UseEndpointArgs } from '../../routesV3.client.types';
+import type { ClientCtx, ServerEnvelope, SocketClient } from '../socket.client.core';
+import { type SocketedRouteDebugOptions } from './socket.client.helper.debug';
+import { type ToRoomsMapper } from './socket.client.helper.rooms';
+type SocketedBuilt<L extends AnyLeafLowProfile> = L['cfg']['feed'] extends true ? BuiltInfinite<L> : BuiltQuery<L>;
+type SocketedRouteResult<L extends AnyLeafLowProfile> = (L['cfg']['feed'] extends true ? InfiniteUseEndpointResultFor<L> : QueryUseEndpointResultFor<L>) & {
+    rooms: string[];
+};
+export type SocketedRouteOptions<L extends AnyLeafLowProfile, Events extends EventMap, C extends SocketConnectionConfigOutput> = {
+    built: SocketedBuilt<L>;
+    toRooms: ToRoomsMapper<L, C>;
+    applySocket: {
+        [K in keyof Events & string]?: (prev: DataShape<L> | undefined, payload: Payload<Events, K>, meta: {
+            envelope?: ServerEnvelope<Events, keyof Events & string>;
+            ctx?: ClientCtx;
+            args: UseEndpointArgs<L>;
+        }) => DataShape<L> | undefined | null;
+    };
+    useSocketClient: () => SocketClient<Events, C>;
+    debug?: SocketedRouteDebugOptions;
+};
+/**
+ * Compose a GET endpoint with socket wiring:
+ * - joins/leaves rooms derived from the endpoint data
+ * - subscribes to a socket event and applies messages to the cache
+ */
+export declare function buildSocketedRoute<L extends AnyLeafLowProfile, Events extends EventMap, C extends SocketConnectionConfigOutput>(options: SocketedRouteOptions<L, Events, C>): Omit<SocketedBuilt<L>, "useEndpoint"> & {
+    useEndpoint: (...useArgs: UseEndpointArgs<L>) => SocketedRouteResult<L>;
+};
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emeryld/rrroutes-client",
-  "version": "2.6.2",
+  "version": "2.6.4",
   "private": false,
   "type": "module",
   "main": "dist/index.cjs",
@@ -19,7 +19,7 @@
     "dist"
   ],
   "dependencies": {
-    "@emeryld/rrroutes-contract": "^2.5.13",
+    "@emeryld/rrroutes-contract": "^2.6.0",
     "zod": "^4.3.6"
   },
   "peerDependencies": {