@pylonsync/react 0.3.292 → 0.3.294

package/dist/useRoom.d.ts

@@ -0,0 +1,93 @@
+import { type SyncEngine } from '@pylonsync/sync';
+export interface RoomPeer {
+    user_id: string;
+    data: any;
+    joined_at: string;
+}
+export interface RoomSnapshot {
+    room: string;
+    peers: RoomPeer[];
+}
+export interface UseRoomOptions {
+    /** Base URL of the pylon server. */
+    baseUrl?: string;
+    /** Auth token for API requests. */
+    token?: string;
+    /** Initial presence data sent on join. */
+    initialPresence?: Record<string, any>;
+    /**
+     * How often (ms) to poll for peer updates WHEN the WebSocket
+     * push channel is unavailable. With a connected WebSocket the SDK
+     * uses `room-subscribe` push and the polling timer never fires.
+     * Defaults to 5_000.
+     */
+    heartbeatInterval?: number;
+}
+export interface UseRoomReturn {
+    /** Current peers in the room (excluding self). */
+    peers: RoomPeer[];
+    /** Whether currently connected to the room. */
+    isConnected: boolean;
+    /** Update your presence data (e.g. cursor position, typing status). */
+    setPresence: (data: Record<string, any>) => void;
+    /** Broadcast a message to the room on a given topic. */
+    broadcast: (topic: string, data: any) => void;
+    /** Leave the room manually. */
+    leave: () => void;
+    /** Error message, if any. */
+    error: string | null;
+}
+interface SharedRoom {
+    /** Number of live React hooks holding this room. */
+    refs: number;
+    /** Has the join() request resolved with a server response? */
+    joined: boolean;
+    /** Cached snapshot for late subscribers (mounting after the join landed). */
+    peers: RoomPeer[];
+    isConnected: boolean;
+    error: string | null;
+    /** Last presence data the caller pushed via setPresence. */
+    presence: Record<string, any>;
+    /** Active heartbeat poll (only set when polling fallback is active). */
+    interval: ReturnType<typeof setInterval> | null;
+    /** Pending teardown — set when refcount hit 0 but we haven't actually
+     *  fired leave yet, to absorb StrictMode mount/unmount/mount races. */
+    pendingTeardown: ReturnType<typeof setTimeout> | null;
+    /** Subscriber callbacks; each useRoom hook registers one. */
+    subs: Set<() => void>;
+    /** Transport identity (frozen at create time — changing it changes the key). */
+    baseUrl: string;
+    token: string | undefined;
+    roomId: string;
+    userId: string;
+    heartbeatInterval: number;
+    /** Sync engine instance the room is attached to (for WS push).
+     *  `null` when none provided / running in SSR or test harness that
+     *  never invoked init(). */
+    engine: SyncEngine | null;
+    /** Unsubscribe handle returned by engine.subscribeRoom. `null` when
+     *  we're polling. Mutually exclusive with `interval` — exactly one
+     *  is set whenever the room is live. */
+    wsUnsubscribe: (() => void) | null;
+    /** Timer that fires PUSH_SNAPSHOT_TIMEOUT_MS after we send the first
+     *  room-subscribe. If a snapshot lands first we cancel it; if it
+     *  fires we assume the server doesn't speak the push protocol and
+     *  fall back to polling. */
+    pushSnapshotTimer: ReturnType<typeof setTimeout> | null;
+    /** Connection-status unsubscribe — fires whenever the engine's
+     *  transport state changes so we can flip between push and polling. */
+    connectionStatusUnsubscribe: (() => void) | null;
+}
+declare function releaseRoom(room: SharedRoom): void;
+export declare const __roomRegistryInternals: {
+    reset(): void;
+    acquire(baseUrl: string, roomId: string, userId: string, token: string | undefined, initialPresence: Record<string, any>, heartbeatInterval: number, engine?: SyncEngine | null): SharedRoom;
+    release: typeof releaseRoom;
+    size(): number;
+    /** Diagnostic: is this room currently on the WS push path? */
+    isWsAttached(room: SharedRoom): boolean;
+    /** Diagnostic: is the polling timer running for this room? */
+    isPolling(room: SharedRoom): boolean;
+};
+export declare function useRoom(roomId: string, userId: string, options?: UseRoomOptions): UseRoomReturn;
+export {};

package/dist/useRouter.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The current query string as a reactive `URLSearchParams`. Re-renders on
+ * client navigation. Returns empty params during SSR / first hydration —
+ * use the `searchParams` page prop for server-side values.
+ *
+ * ```tsx
+ * const params = useSearchParams();
+ * const tab = params.get("tab") ?? "overview";
+ * ```
+ */
+export declare function useSearchParams(): URLSearchParams;
+/**
+ * The current pathname (no query/hash), reactive to client navigation.
+ * Returns "/" during SSR / first hydration — use the `url` page prop for
+ * server-side values.
+ */
+export declare function usePathname(): string;
+/**
+ * The current route's dynamic params — e.g. `/dashboard/[projectId]` →
+ * `{ projectId: "p_1" }`. Reactive to client navigation, so a deep child gets
+ * the new params after a `<Link>` click without prop-drilling. Returns `{}`
+ * during SSR / first hydration — use the `params` page prop for server-side
+ * values. Drop-in for Next's `useParams`.
+ *
+ * ```tsx
+ * const { projectId } = useParams<{ projectId: string }>();
+ * ```
+ */
+export declare function useParams<T extends Record<string, string> = Record<string, string>>(): T;
+/**
+ * Client-side redirect — replaces the current history entry with `href`.
+ * Drop-in for Next's `redirect` when called from a client component
+ * (effect/handler). For a redirect decided during a server render, use the
+ * `response.redirect()` API on the page's `PageProps` instead.
+ */
+export declare function redirect(href: string): void;
+/** Error thrown by {@link notFound}; the SSR not-found boundary renders it. */
+export declare class NotFoundError extends Error {
+    readonly digest = "PYLON_NOT_FOUND";
+    constructor();
+}
+/**
+ * Render the nearest `not-found.tsx` boundary from a client component by
+ * throwing — drop-in for Next's `notFound`. For a 404 decided during a server
+ * render, prefer `response.notFound()` on the page's `PageProps` so the
+ * response carries a real 404 status.
+ */
+export declare function notFound(): never;
+/** Imperative navigation handle (Next-style `useRouter`). */
+export interface PylonRouter {
+    /** Navigate to `href`, pushing a new history entry. */
+    push(href: string): void;
+    /** Navigate to `href`, replacing the current history entry. */
+    replace(href: string): void;
+    /** Go back one history entry. */
+    back(): void;
+    /** Go forward one history entry. */
+    forward(): void;
+    /** Re-fetch + re-render the current route (fresh server data). */
+    refresh(): void;
+    /** Warm the SSR HTML + chunks for `href` ahead of a navigation. */
+    prefetch(href: string): void;
+}
+/**
+ * Programmatic client navigation. Methods are no-ops before hydration /
+ * during SSR (there's no client runtime yet), so they're safe to call from
+ * effects and event handlers.
+ *
+ * ```tsx
+ * const router = useRouter();
+ * <button onClick={() => router.push("/dashboard")}>Go</button>
+ * ```
+ */
+export declare function useRouter(): PylonRouter;

package/dist/useSession.d.ts

@@ -0,0 +1,41 @@
+import { SyncEngine, type ResolvedSession } from "@pylonsync/sync";
+export type { ResolvedSession };
+export interface UseSessionReturn {
+    /** Server-resolved session. `userId=null` means anonymous. */
+    session: ResolvedSession;
+    /** Convenience accessors. */
+    userId: string | null;
+    tenantId: string | null;
+    isAdmin: boolean;
+    isAuthenticated: boolean;
+    /**
+     * Switch the active tenant. POSTs to /api/auth/select-org, verifies
+     * membership server-side, resets the local replica so stale rows
+     * from the previous tenant disappear, and refreshes the cached
+     * session — all in one await. Throws (with `.code`/`.status`) on
+     * NOT_A_MEMBER and other server errors.
+     */
+    selectOrg: (orgId: string) => Promise<void>;
+    /** Drop the active tenant (back to no-org state). */
+    clearOrg: () => Promise<void>;
+    /** Revoke the current session server-side and refresh. */
+    signOut: () => Promise<void>;
+    /**
+     * Escape hatch — refresh the cached session without mutating it.
+     * Most apps shouldn't need this; the helpers above already include
+     * a refresh. Useful when app code calls /api/auth/* via its own
+     * client and needs the engine to observe the change.
+     */
+    refresh: () => Promise<void>;
+}
+/**
+ * Subscribe to the server-resolved session held by the sync engine.
+ *
+ * The engine fetches `/api/auth/me` on start and on token flips, caches
+ * the result, and notifies the store on change — so this hook is
+ * purely a reader. The exposed helpers (selectOrg, clearOrg, signOut)
+ * combine the server fetch + cache refresh + replica reset into one
+ * call so app code doesn't need to remember the manual
+ * `notifySessionChanged()` step after every auth mutation.
+ */
+export declare function useSession(sync: SyncEngine): UseSessionReturn;

package/dist/useShard.d.ts

@@ -0,0 +1,58 @@
+export interface UseShardOptions {
+    /** Subscriber ID (usually the logged-in user ID). Required for multiplayer. */
+    subscriberId: string;
+    /**
+     * Auth token. Sent over the WebSocket as a Sec-WebSocket-Protocol
+     * subprotocol header in the form `"bearer.<token>"`. This keeps the token
+     * out of URLs — proxy logs, browser devtools network panel, and error
+     * telemetry typically record the URL but not the subprotocol value.
+     *
+     * The pylon shard server reads either the subprotocol header or the
+     * legacy `?token=` query param (which is still accepted but deprecated —
+     * scheduled for removal in a future release).
+     */
+    token?: string;
+    /** Override the base URL. Defaults to `window.location.host`. */
+    baseUrl?: string;
+    /** Override the shard WS port (default: HTTP port + 3). */
+    wsPort?: number;
+    /** Explicit WebSocket URL. Overrides baseUrl/wsPort. */
+    wsUrl?: string;
+    /** If true, falls back to SSE + HTTP POST if WebSocket fails (default: true). */
+    sseFallback?: boolean;
+    /** Reconnect on unexpected close (default: true). */
+    autoReconnect?: boolean;
+    /** Reconnect backoff in ms (default: starts at 500, maxes at 10_000). */
+    reconnectBackoffMs?: number;
+}
+export interface UseShardReturn<TSnapshot = unknown, TInput = unknown> {
+    snapshot: TSnapshot | null;
+    tick: number;
+    connected: boolean;
+    error: Error | null;
+    /** Send an input to the shard. Returns a client sequence number. */
+    send: (input: TInput) => number;
+    /** Close the connection early. */
+    close: () => void;
+}
+export interface ShardClient<TSnapshot = unknown, TInput = unknown> {
+    onSnapshot: (fn: (snapshot: TSnapshot, tick: number) => void) => void;
+    onError: (fn: (err: Error) => void) => void;
+    onOpen: (fn: () => void) => void;
+    onClose: (fn: () => void) => void;
+    send: (input: TInput) => number;
+    close: () => void;
+    readonly connected: boolean;
+}
+/**
+ * Connect to a shard without React — returns a typed client you can wire
+ * into any framework.
+ */
+export declare function connectShard<TSnapshot = unknown, TInput = unknown>(shardId: string, options: UseShardOptions): ShardClient<TSnapshot, TInput>;
+/**
+ * React hook that subscribes to a shard's snapshots and provides a send fn.
+ *
+ * The hook re-renders when a new snapshot arrives or the connection state
+ * changes. The `send` fn is stable across re-renders.
+ */
+export declare function useShard<TSnapshot = unknown, TInput = unknown>(shardId: string, options: UseShardOptions): UseShardReturn<TSnapshot, TInput>;

package/dist/useSyncStatus.d.ts

@@ -0,0 +1,30 @@
+import { type SyncConnectionStatus, type SyncEngine } from "@pylonsync/sync";
+export type { SyncConnectionStatus };
+/**
+ * Subscribe to the sync engine's connection status. Re-renders whenever
+ * the WebSocket transitions ("connecting" → "connected" → "reconnecting"
+ * → "offline"), so apps can render a small indicator without polling
+ * or wiring their own event listeners.
+ *
+ * Common use case: surface a "reconnecting…" banner during the cold
+ * start after a Fly autostop or a flaky network. Live queries keep
+ * returning the last-known data during reconnect, so without this hook
+ * users see stale data with no signal that anything is wrong.
+ *
+ * ```tsx
+ * function ConnectionBanner() {
+ *   const status = useSyncStatus();
+ *   if (status === "connected") return null;
+ *   return (
+ *     <div className="banner">
+ *       {status === "reconnecting" ? "Reconnecting…" : "Offline"}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * Pass an explicit `engine` if your app uses a non-default sync
+ * instance; otherwise omit and the hook reads the singleton wired up
+ * by `init()`.
+ */
+export declare function useSyncStatus(engine?: SyncEngine): SyncConnectionStatus;

package/package.json

@@ -3,22 +3,28 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.292",
+  "version": "0.3.294",
   "type": "module",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "./src/index.ts",
+  "types": "./dist/index.d.ts",
   "scripts": {
-    "build": "tsc -p tsconfig.json --noEmit",
-    "check": "tsc -p tsconfig.json --noEmit"
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "prepack": "bun run build"
   },
   "dependencies": {
-    "@pylonsync/sdk": "0.3.292",
-    "@pylonsync/sync": "0.3.292"
+    "@pylonsync/sdk": "0.3.294",
+    "@pylonsync/sync": "0.3.294"
   },
   "peerDependencies": {
     "react": ">=19.0.0"
   },
   "devDependencies": {
     "@types/react": "^19.0.0"
-  }
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md"
+  ]
 }

package/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "types": ["bun-types"]
-  },
-  "include": [
-    "src"
-  ]
-}
-