@pantheon-systems/css-client 0.4.0

package/dist/jwt-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt-utils.d.ts","sourceRoot":"","sources":["../src/jwt-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAU7E;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI3D;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAK/D;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CASnE"}

package/dist/jwt-utils.js

@@ -0,0 +1,45 @@
+/**
+ * JWT Utility Functions
+ *
+ * Shared helpers for parsing JWT payloads and checking expiry.
+ * These decode JWTs for display/routing only — no cryptographic verification.
+ */
+export const TOKEN_REFRESH_BUFFER_SECONDS = 300;
+export function parseJwtPayload(token) {
+    try {
+        const parts = token.split('.');
+        const payload = parts[1];
+        if (!payload)
+            return null;
+        const decoded = atob(payload.replace(/-/g, '+').replace(/_/g, '/'));
+        return JSON.parse(decoded);
+    }
+    catch {
+        return null;
+    }
+}
+export function getTokenExpiry(token) {
+    const payload = parseJwtPayload(token);
+    if (!payload || typeof payload.exp !== 'number')
+        return null;
+    return payload.exp;
+}
+export function isTokenExpiredOrExpiring(token) {
+    const exp = getTokenExpiry(token);
+    if (exp === null)
+        return false;
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    return nowSeconds >= exp - TOKEN_REFRESH_BUFFER_SECONDS;
+}
+export function extractUserInfo(token) {
+    const payload = parseJwtPayload(token);
+    if (!payload || typeof payload.sub !== 'string')
+        return null;
+    return {
+        id: payload.sub,
+        email: payload.email,
+        name: payload.name,
+        picture: payload.picture,
+    };
+}
+//# sourceMappingURL=jwt-utils.js.map

package/dist/jwt-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt-utils.js","sourceRoot":"","sources":["../src/jwt-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAC;AAEhD,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACzB,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC;QAC1B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;QACpE,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAA4B,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,MAAM,OAAO,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACvC,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC7D,OAAO,OAAO,CAAC,GAAG,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,KAAa;IACpD,MAAM,GAAG,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC/B,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IACjD,OAAO,UAAU,IAAI,GAAG,GAAG,4BAA4B,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,MAAM,OAAO,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACvC,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC7D,OAAO;QACL,EAAE,EAAE,OAAO,CAAC,GAAG;QACf,KAAK,EAAE,OAAO,CAAC,KAA2B;QAC1C,IAAI,EAAE,OAAO,CAAC,IAA0B;QACxC,OAAO,EAAE,OAAO,CAAC,OAA6B;KAC/C,CAAC;AACJ,CAAC"}

package/dist/oauth.d.ts

@@ -0,0 +1,64 @@
+import type { AuthProvider } from './auth.js';
+/** User info returned from OAuth providers */
+export interface OAuthUserInfo {
+    id: string;
+    email?: string;
+    name?: string;
+    picture?: string;
+}
+export interface OAuthSession {
+    provider: 'broker';
+    login(): Promise<void>;
+    logout(): Promise<void>;
+    isAuthenticated(): boolean;
+    getUserInfo(): OAuthUserInfo | null;
+    getToken(): Promise<string | null>;
+}
+/**
+ * Create an AuthProvider from an OAuthSession.
+ * The returned AuthProvider is compatible with P1Client's authProvider config option.
+ *
+ * @param session - The OAuth session to derive the auth provider from
+ * @returns AuthProvider function that returns `Bearer <token>`
+ */
+export declare function createOAuthAuthProvider(session: OAuthSession): AuthProvider;
+export interface AuthMeResponse {
+    id: string;
+    type: string;
+    email?: string;
+    name?: string;
+    avatarUrl?: string;
+    authProvider?: string;
+    tokenExpiry?: string;
+    providerSubjectId?: string;
+}
+/**
+ * Validate a token against the P1 backend's /api/auth/me endpoint.
+ * Framework-agnostic — works in any JS environment with fetch().
+ *
+ * @param baseUrl - P1 backend base URL (e.g., "http://localhost:8787")
+ * @param token - Bearer token to validate
+ * @returns The authenticated user info, or null if the token is invalid
+ */
+export declare function validateToken(baseUrl: string, token: string): Promise<AuthMeResponse | null>;
+/**
+ * Login as a mock/demo user via POST /api/auth/token.
+ * Framework-agnostic — works in any JS environment with fetch().
+ *
+ * @internal This is a local-development helper. The backend only enables
+ * `/api/auth/token` when `ENVIRONMENT === 'local'`; mock tokens are rejected
+ * by all other environments. Do not use in production deployments.
+ *
+ * @param baseUrl - P1 backend base URL
+ * @param userId - The mock user ID to log in as
+ * @returns Token and user info
+ */
+export declare function loginMockUser(baseUrl: string, userId: string): Promise<{
+    token: string;
+    user: {
+        id: string;
+        name: string;
+        email: string;
+    };
+}>;
+//# sourceMappingURL=oauth.d.ts.map

package/dist/oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAG9C,8CAA8C;AAC9C,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,eAAe,IAAI,OAAO,CAAC;IAC3B,WAAW,IAAI,aAAa,GAAG,IAAI,CAAC;IACpC,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACpC;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,YAAY,GAAG,YAAY,CAQ3E;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAUhC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC,CAgB/E"}

package/dist/oauth.js

@@ -0,0 +1,62 @@
+/**
+ * Create an AuthProvider from an OAuthSession.
+ * The returned AuthProvider is compatible with P1Client's authProvider config option.
+ *
+ * @param session - The OAuth session to derive the auth provider from
+ * @returns AuthProvider function that returns `Bearer <token>`
+ */
+export function createOAuthAuthProvider(session) {
+    return async () => {
+        const token = await session.getToken();
+        if (!token) {
+            throw new Error('No OAuth token available. Please log in first.');
+        }
+        return `Bearer ${token}`;
+    };
+}
+/**
+ * Validate a token against the P1 backend's /api/auth/me endpoint.
+ * Framework-agnostic — works in any JS environment with fetch().
+ *
+ * @param baseUrl - P1 backend base URL (e.g., "http://localhost:8787")
+ * @param token - Bearer token to validate
+ * @returns The authenticated user info, or null if the token is invalid
+ */
+export async function validateToken(baseUrl, token) {
+    try {
+        const response = await fetch(`${baseUrl}/api/auth/me`, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!response.ok)
+            return null;
+        return (await response.json());
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Login as a mock/demo user via POST /api/auth/token.
+ * Framework-agnostic — works in any JS environment with fetch().
+ *
+ * @internal This is a local-development helper. The backend only enables
+ * `/api/auth/token` when `ENVIRONMENT === 'local'`; mock tokens are rejected
+ * by all other environments. Do not use in production deployments.
+ *
+ * @param baseUrl - P1 backend base URL
+ * @param userId - The mock user ID to log in as
+ * @returns Token and user info
+ */
+export async function loginMockUser(baseUrl, userId) {
+    const response = await fetch(`${baseUrl}/api/auth/token`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ userId }),
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({ error: 'Login failed' }));
+        throw new Error(error.error ?? 'Login failed');
+    }
+    return response.json();
+}
+//# sourceMappingURL=oauth.js.map

package/dist/oauth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.js","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"AAoBA;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAqB;IAC3D,OAAO,KAAK,IAAI,EAAE;QAChB,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC;QACvC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACpE,CAAC;QACD,OAAO,UAAU,KAAK,EAAE,CAAC;IAC3B,CAAC,CAAC;AACJ,CAAC;AAaD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAe,EACf,KAAa;IAEb,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,OAAO,cAAc,EAAE;YACrD,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,KAAK,EAAE,EAAE;SAC9C,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QAC9B,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAmB,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAe,EACf,MAAc;IAEd,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,OAAO,iBAAiB,EAAE;QACxD,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;KACjC,CAAC,CAAC;IAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC;QAC7E,MAAM,IAAI,KAAK,CAAE,KAA4B,CAAC,KAAK,IAAI,cAAc,CAAC,CAAC;IACzE,CAAC;IAED,OAAO,QAAQ,CAAC,IAAI,EAGlB,CAAC;AACL,CAAC"}

package/dist/realtime.d.ts

@@ -0,0 +1,314 @@
+/**
+ * Phase 2.1: RealtimeClient
+ *
+ * WebSocket-based real-time collaboration client using Yjs CRDT.
+ * Provides bidirectional sync between client and DocumentSession Durable Object.
+ * Uses ReconnectingWebSocket from partysocket for automatic reconnection with exponential backoff.
+ */
+import * as Y from 'yjs';
+import type { ActorPresence, ActorState, PublishResult } from './types';
+/**
+ * Configuration for reconnection behavior
+ */
+export interface ReconnectionConfig {
+    /**
+     * Maximum number of reconnection attempts.
+     * Set to Infinity for unlimited retries.
+     * @default Infinity
+     */
+    maxRetries?: number;
+    /**
+     * Minimum delay between reconnection attempts in milliseconds.
+     * @default 1000
+     */
+    minReconnectionDelay?: number;
+    /**
+     * Maximum delay between reconnection attempts in milliseconds.
+     * @default 30000
+     */
+    maxReconnectionDelay?: number;
+    /**
+     * Factor by which to multiply the delay for each retry (exponential backoff).
+     * @default 1.5
+     */
+    reconnectionDelayGrowFactor?: number;
+}
+/**
+ * Configuration for the RealtimeClient
+ */
+export interface RealtimeClientConfig {
+    /**
+     * Base URL for WebSocket connections.
+     * Can be ws:// or wss:// protocol.
+     * Example: "wss://api.example.com" or "ws://localhost:8787"
+     */
+    baseUrl: string;
+    /**
+     * API key for authentication.
+     * Will be passed as a query parameter since browsers can't send
+     * custom headers with WebSocket upgrade requests.
+     */
+    apiKey?: string;
+    /**
+     * Callback when document state is updated (from remote changes)
+     */
+    onUpdate?: (snapshot: Record<string, unknown>) => void;
+    /**
+     * Callback when WebSocket connection is established
+     */
+    onConnect?: () => void;
+    /**
+     * Callback when WebSocket connection is closed
+     */
+    onDisconnect?: () => void;
+    /**
+     * Callback when an error occurs
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Callback when attempting to reconnect after a connection loss.
+     * Called with the current retry attempt number.
+     */
+    onReconnecting?: (attempt: number) => void;
+    /**
+     * Callback when authorization fails (WebSocket close code 4401 or 4403).
+     * This indicates the session is invalid or the agent lacks permission.
+     * When this is called, the client will NOT attempt to reconnect.
+     */
+    onAuthorizationError?: (error: Error) => void;
+    /**
+     * Callback when presence update is received from server.
+     * Called with the full list of actors in the document.
+     */
+    onPresenceUpdate?: (actors: ActorPresence[]) => void;
+    /**
+     * Callback when another actor updates their focus regions.
+     * Called with the actor ID and their new focus regions.
+     */
+    onFocusRegionBroadcast?: (actorId: string, focusRegions: string[]) => void;
+    /**
+     * Configuration for automatic reconnection behavior.
+     */
+    reconnection?: ReconnectionConfig;
+    /**
+     * Callback when the server sends a RATE_LIMITED error.
+     * The client remains connected; this is informational.
+     */
+    onRateLimited?: () => void;
+    /**
+     * Optional token refresher for dynamic WebSocket authentication.
+     * Called when the WebSocket connection closes unexpectedly (non-intentionally).
+     * Should return a fresh token string, or null if the session cannot be refreshed.
+     * The fresh token is used in subsequent reconnection URLs.
+     */
+    tokenRefresher?: () => Promise<string | null>;
+}
+/**
+ * Parameters for connecting to a document session
+ */
+export interface ConnectionParams {
+    /** Site ID */
+    siteId: string;
+    /** Branch ID */
+    branchId: string;
+    /** Document path (e.g., "pages/home") */
+    documentPath: string;
+    /** Actor ID (user or agent ID) */
+    actorId: string;
+    /** Actor type */
+    actorType: 'user' | 'agent';
+    /**
+     * Session ID for agent authorization.
+     * Required for agents, obtained from startEdit() response.
+     * Enables server-side enforcement of the Agent Politeness Protocol.
+     */
+    sessionId?: string;
+}
+/**
+ * Real-time collaboration client using Yjs CRDT over WebSocket.
+ * Uses PartySocket for automatic reconnection with exponential backoff.
+ *
+ * @example
+ * ```typescript
+ * const client = new RealtimeClient({
+ *   baseUrl: 'wss://api.example.com',
+ *   onUpdate: (snapshot) => {
+ *     console.log('Document updated:', snapshot);
+ *   },
+ *   onReconnecting: (attempt) => {
+ *     console.log(`Reconnecting... attempt ${attempt}`);
+ *   },
+ *   reconnection: {
+ *     maxRetries: 10,
+ *     minReconnectionDelay: 1000,
+ *     maxReconnectionDelay: 30000,
+ *   },
+ * });
+ *
+ * client.connect({
+ *   siteId: 'site-123',
+ *   branchId: 'branch-456',
+ *   documentPath: 'pages/home',
+ *   actorId: 'user-789',
+ *   actorType: 'user',
+ * });
+ *
+ * // When done
+ * client.disconnect();
+ * ```
+ */
+export declare class RealtimeClient {
+    private readonly config;
+    private readonly ydoc;
+    private ws;
+    private connected;
+    private intentionalDisconnect;
+    private currentApiKey;
+    private tokenRefreshInFlight;
+    private hasConnectedOnce;
+    private lastReportedRetryCount;
+    private reconnectCheckInterval;
+    private visibilityHandler;
+    private sendTimestamps;
+    private pendingUpdates;
+    private flushTimer;
+    private static readonly RATE_THRESHOLD;
+    private static readonly RATE_WINDOW_MS;
+    private lastSentSnapshot;
+    private pendingDeliveryAcks;
+    private static readonly DELIVERY_ACK_TIMEOUT_MS;
+    private pendingPublishRequests;
+    private static readonly PUBLISH_TIMEOUT_MS;
+    private pendingActionMetadata;
+    constructor(config: RealtimeClientConfig);
+    /**
+     * Connect to a document session via WebSocket.
+     * Uses PartySocket for automatic reconnection on connection loss.
+     *
+     * @param params - Connection parameters including site, branch, document, and actor info
+     */
+    connect(params: ConnectionParams): void;
+    /**
+     * Start monitoring for reconnection attempts by polling retryCount.
+     * This is needed because PartySocket doesn't expose a reconnection callback.
+     */
+    private startReconnectMonitoring;
+    /**
+     * Stop the reconnection monitoring interval.
+     */
+    private stopReconnectMonitoring;
+    /**
+     * Start monitoring for page visibility changes.
+     * When the page becomes visible after being hidden, check connection health
+     * and force a reconnection sync if needed.
+     */
+    private startVisibilityMonitoring;
+    /**
+     * Stop visibility change monitoring.
+     */
+    private stopVisibilityMonitoring;
+    /**
+     * Disconnect from the current session.
+     * This permanently closes the connection and stops any reconnection attempts.
+     */
+    disconnect(): void;
+    /**
+     * Apply a local Yjs update.
+     * This is typically called from Puck-Yjs binding when local edits occur.
+     * Uses rate-aware sending to avoid exceeding the server's rate limit.
+     *
+     * @param update - Raw Yjs update bytes
+     */
+    applyLocalUpdate(update: Uint8Array): void;
+    /**
+     * Set pending action metadata to be sent after the next CRDT update.
+     * The metadata is best-effort — if the WebSocket is not open or the
+     * send fails, the CRDT update still goes through without metadata.
+     *
+     * @param meta - Action type and metadata from Puck's onAction callback
+     */
+    setActionMetadata(meta: {
+        actionType: string;
+        actionMetadata: Record<string, unknown>;
+    } | null): void;
+    /**
+     * Send any pending action metadata as a text message and clear it.
+     * Called after a CRDT update is sent to associate the metadata with
+     * the most recent edit.
+     */
+    sendPendingActionMetadata(): void;
+    /**
+     * Send a Yjs update with rate awareness.
+     * Sends immediately when under the threshold (40 msgs/sec).
+     * Buffers and coalesces updates when approaching the server's 50 msg/sec limit.
+     */
+    private rateLimitedSend;
+    /**
+     * Schedule a flush of buffered updates after the rate window resets.
+     */
+    private scheduleFlush;
+    /**
+     * Flush all buffered updates as a single coalesced message.
+     */
+    private flushPendingUpdates;
+    /**
+     * Get the current document snapshot as JSON.
+     */
+    getSnapshot(): Record<string, unknown>;
+    /**
+     * Get the underlying Y.Doc for direct manipulation.
+     * Use with caution - prefer using the Puck-Yjs binding utilities.
+     */
+    getYDoc(): Y.Doc;
+    /**
+     * Check if currently connected.
+     */
+    isConnected(): boolean;
+    /**
+     * Check if presence updates are available via WebSocket.
+     * Returns true when connected and able to send/receive presence messages.
+     */
+    get presenceViaWebSocket(): boolean;
+    /**
+     * Send focus regions update to the server.
+     * @param focusRegions - JSON paths the actor is focused on
+     * @returns true if message was sent, false if not connected
+     */
+    sendFocusRegions(focusRegions: string[]): boolean;
+    /**
+     * Send a presence heartbeat to keep the connection alive.
+     * @param state - Optional state update (active, idle, editing)
+     */
+    sendHeartbeat(state?: ActorState): void;
+    /**
+     * Wait for the server to acknowledge that all preceding WebSocket messages
+     * have been processed. This uses TCP ordering guarantees: a text frame sent
+     * after binary CRDT updates is guaranteed to arrive after those updates.
+     * The server echoes back a delivery_ack with the matching requestId.
+     *
+     * Used before publish to ensure the Durable Object has received and applied
+     * the latest edits before the HTTP publish request arrives.
+     *
+     * @returns Promise that resolves when the server confirms delivery
+     * @throws Error if not connected or if timeout expires (5 seconds)
+     */
+    waitForDelivery(): Promise<void>;
+    /**
+     * Request the server to publish the current document via WebSocket.
+     * TCP ordering guarantees all preceding binary CRDT updates have been
+     * processed before this message is handled, eliminating stale-version races.
+     *
+     * The Durable Object handles the entire flow: flush to Postgres, then
+     * call /internal/publish to create the checkpoint.
+     *
+     * @returns Promise that resolves with the publish result
+     * @throws Error if not connected or if timeout expires (30 seconds)
+     */
+    requestPublish(): Promise<PublishResult>;
+    /**
+     * Handle incoming text (JSON) messages for presence protocol.
+     * @param data - Raw JSON string from WebSocket
+     */
+    private handleTextMessage;
+}
+//# sourceMappingURL=realtime.d.ts.map

package/dist/realtime.d.ts.map

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