@rool-dev/sdk 0.6.0-dev.1cbaafa → 0.6.0-dev.4595e79

package/README.md

@@ -83,20 +83,15 @@ channel.close();
 A **space** is a container that holds objects, schema, metadata, and channels. A **channel** is a named context within a space — it's the handle you use for all object and AI operations. Each channel contains one or more **conversations**, each with independent interaction history.
 
 There are two main handles:
-- **`RoolSpace`** — Live handle with SSE subscription for user management, link access, channel management, export, and channel lifecycle events. Extends `EventEmitter`.
+- **`RoolSpace`** — Lightweight admin handle for user management, link access, channel management, and export. No real-time subscription.
 - **`RoolChannel`** — Full real-time handle for objects, AI prompts, media, schema, and undo/redo.
 
 ```typescript
-// Open a space — live handle with SSE subscription
+// Open a space for admin operations
 const space = await client.openSpace('space-id');
 await space.addUser(userId, 'editor');
 await space.setLinkAccess('viewer');
 
-// React to channel changes in real-time
-space.on('channelCreated', (channel) => console.log('New channel:', channel.id));
-space.on('channelUpdated', (channel) => console.log('Updated:', channel.id));
-space.on('channelDeleted', (channelId) => console.log('Deleted:', channelId));
-
 // Open a channel for object and AI operations
 const channel = await client.openChannel('space-id', 'my-channel');
 await channel.prompt('Create some planets');
@@ -104,9 +99,6 @@ await channel.prompt('Create some planets');
 // Or open a channel via the space handle
 const channel2 = await space.openChannel('research');
 await channel2.prompt('Analyze the data');  // Independent channel
-
-// Clean up — stops subscription and closes all open channels
-space.close();
 ```
 
 The `channelId` is fixed when you open a channel and cannot be changed. To use a different channel, open a new one. Channels to the same space share the same objects and schema.
@@ -576,9 +568,9 @@ const client = new RoolClient({
 | Method | Description |
 |--------|-------------|
 | `listSpaces(): Promise<RoolSpaceInfo[]>` | List available spaces |
-| `openSpace(spaceId): Promise<RoolSpace>` | Open a space with live SSE subscription. Caches and reuses open spaces. |
+| `openSpace(spaceId): Promise<RoolSpace>` | Open a space for admin operations (no real-time subscription) |
 | `openChannel(spaceId, channelId): Promise<RoolChannel>` | Open a channel on a space |
-| `createSpace(name): Promise<RoolSpace>` | Create a new space, returns live handle with SSE subscription |
+| `createSpace(name): Promise<RoolSpace>` | Create a new space, returns admin handle |
 | `deleteSpace(id): Promise<void>` | Permanently delete a space (cannot be undone) |
 | `importArchive(name, archive): Promise<RoolSpace>` | Import from a zip archive, creating a new space |
 
@@ -590,8 +582,7 @@ Manage channels within a space. Available on both the client and space handles:
 |--------|-------------|
 | `client.renameChannel(spaceId, channelId, name): Promise<void>` | Rename a channel |
 | `client.deleteChannel(spaceId, channelId): Promise<void>` | Delete a channel and its interaction history |
-| `space.channels: ChannelInfo[]` | Live channel list (auto-updates via SSE) |
-| `space.getChannels(): ChannelInfo[]` | List channels (deprecated — use `space.channels` instead) |
+| `space.getChannels(): ChannelInfo[]` | List channels (from cached snapshot) |
 | `space.deleteChannel(channelId): Promise<void>` | Delete a channel |
 | `channel.rename(name): Promise<void>` | Rename the current channel |
 
@@ -677,15 +668,13 @@ client.on('spaceAdded', (space: RoolSpaceInfo) => void)      // Space created or
 client.on('spaceRemoved', (spaceId: string) => void)         // Space deleted or access revoked
 client.on('spaceRenamed', (spaceId: string, newName: string) => void)
 client.on('channelCreated', (spaceId: string, channel: ChannelInfo) => void)
-client.on('channelUpdated', (spaceId: string, channel: ChannelInfo) => void)
+client.on('channelRenamed', (spaceId: string, channelId: string, newName: string) => void)
 client.on('channelDeleted', (spaceId: string, channelId: string) => void)
 client.on('userStorageChanged', ({ key, value, source }: UserStorageChangedEvent) => void)
 client.on('connectionStateChanged', (state: 'connected' | 'disconnected' | 'reconnecting') => void)
 client.on('error', (error: Error, context?: string) => void)
 ```
 
-Channel events on the client (`channelCreated`, `channelUpdated`, `channelDeleted`) are pass-throughs from space events for backwards compatibility. Prefer listening on the space handle directly for new code.
-
 **Space list management pattern:**
 ```typescript
 const spaces = new Map<string, RoolSpaceInfo>();
@@ -700,9 +689,7 @@ client.on('spaceRenamed', (id, name) => {
 
 ## RoolSpace API
 
-A space handle with a live SSE subscription. Extends `EventEmitter`. Manages user access, link sharing, channels, and export. The `channels` property auto-updates via SSE, and channel lifecycle events fire in real-time.
-
-`openSpace()` caches and reuses open spaces — calling it twice with the same ID returns the same instance. Call `close()` when done to stop the subscription and close all open channels.
+A space is a lightweight admin handle for space-level operations. It does not have a real-time subscription — use channels for live data and object operations.
 
 ### Properties
 
@@ -713,34 +700,23 @@ A space handle with a live SSE subscription. Extends `EventEmitter`. Manages use
 | `role: RoolUserRole` | User's role |
 | `linkAccess: LinkAccess` | URL sharing level |
 | `memberCount: number` | Number of users with access to the space |
-| `channels: ChannelInfo[]` | Live channel list (auto-updates via SSE) |
 
 ### Methods
 
 | Method | Description |
 |--------|-------------|
 | `openChannel(channelId): Promise<RoolChannel>` | Open a channel on this space |
-| `close(): void` | Stop SSE subscription and close all open channels |
 | `rename(newName): Promise<void>` | Rename this space |
 | `delete(): Promise<void>` | Permanently delete this space |
 | `listUsers(): Promise<SpaceMember[]>` | List users with access |
 | `addUser(userId, role): Promise<void>` | Add user to space |
 | `removeUser(userId): Promise<void>` | Remove user from space |
 | `setLinkAccess(linkAccess): Promise<void>` | Set URL sharing level |
-| `getChannels(): ChannelInfo[]` | List channels (deprecated — use `channels` property instead) |
+| `getChannels(): ChannelInfo[]` | List channels (from cached snapshot) |
 | `deleteChannel(channelId): Promise<void>` | Delete a channel |
 | `exportArchive(): Promise<Blob>` | Export space as zip archive |
 | `refresh(): Promise<void>` | Refresh space data from server |
 
-### Space Events
-
-```typescript
-space.on('channelCreated', (channel: ChannelInfo) => void)   // New channel added
-space.on('channelUpdated', (channel: ChannelInfo) => void)   // Channel metadata changed (name, extension, manifest)
-space.on('channelDeleted', (channelId: string) => void)      // Channel removed
-space.on('connectionStateChanged', (state: 'connected' | 'disconnected' | 'reconnecting') => void)
-```
-
 ## RoolChannel API
 
 A channel is a named context within a space. All object operations, AI prompts, and real-time sync go through a channel. The `channelId` is fixed at open time — to use a different channel, open a new one.

package/dist/client.d.ts

@@ -1,11 +1,11 @@
 import { EventEmitter } from './event-emitter.js';
+import { RoolChannel } from './channel.js';
 import { RoolSpace } from './space.js';
 import type { RoolClientConfig, RoolClientEvents, RoolSpaceInfo, CurrentUser, UserResult, AuthUser, ExtensionInfo, PublishedExtensionInfo, UploadExtensionOptions, FindExtensionsOptions } from './types.js';
-import type { RoolChannel } from './channel.js';
 /**
  * Rool Client - Manages authentication, space lifecycle, and shared infrastructure.
  *
- * The client is lightweight - most operations happen on RoolSpace and RoolChannel instances.
+ * The client is lightweight - most operations happen on RoolChannel instances.
  *
  * Features:
  * - Authentication (login, logout, token management)
@@ -21,7 +21,9 @@ export declare class RoolClient extends EventEmitter<RoolClientEvents> {
     private graphqlClient;
     private subscriptionManager;
     private logger;
-    private openSpaces;
+    private openChannels;
+    private spaceSubscriptions;
+    private spaceDataCache;
     private _storageCache;
     private _currentUser;
     constructor(config?: RoolClientConfig);
@@ -99,23 +101,24 @@ export declare class RoolClient extends EventEmitter<RoolClientEvents> {
     listSpaces(): Promise<RoolSpaceInfo[]>;
     /**
      * Open a channel on a space.
-     * Convenience method that opens (or reuses) the space, then opens the channel.
+     * Fetches full space data, ensures the channel exists, and starts the
+     * shared space subscription if not already active.
      *
      * @param spaceId - The ID of the space
      * @param channelId - The channel ID (created if it doesn't exist)
      */
     openChannel(spaceId: string, channelId: string): Promise<RoolChannel>;
     /**
-     * Open a space with a real-time subscription.
-     * Returns a live RoolSpace handle with channel lifecycle events.
-     * Reuses an existing handle if the space is already open.
+     * Open a space for admin operations.
+     * Returns a lightweight handle for user management, link access,
+     * channel management, and export. Does not start a real-time subscription.
      *
-     * Call space.close() when done to stop the subscription.
+     * To work with objects and AI, call space.openChannel(channelId).
      */
     openSpace(spaceId: string): Promise<RoolSpace>;
     /**
      * Create a new space.
-     * Returns a RoolSpace handle with a real-time subscription.
+     * Returns a RoolSpace handle for admin operations.
      * Call space.openChannel(channelId) to start working with objects.
      */
     createSpace(name: string): Promise<RoolSpace>;
@@ -207,6 +210,7 @@ export declare class RoolClient extends EventEmitter<RoolClientEvents> {
     /**
      * Ensure the client-level event subscription is active.
      * Called automatically when opening spaces.
+     * Also fetches and caches the current user ID.
      * @internal
      */
     private ensureSubscribed;
@@ -226,10 +230,31 @@ export declare class RoolClient extends EventEmitter<RoolClientEvents> {
      * @internal Not part of the public API — use typed methods instead.
      */
     _graphql<T>(query: string, variables?: Record<string, unknown>): Promise<T>;
+    private registerChannel;
+    private unregisterChannel;
+    /**
+     * Get space data, using a short-lived cache so concurrent openChannel calls
+     * for the same space share one fetch.
+     */
+    private getSpaceData;
+    /**
+     * Ensure a shared space subscription exists for the given spaceId.
+     * Creates one if it doesn't exist yet. Returns when connected.
+     */
+    private ensureSpaceSubscription;
+    /**
+     * Route a space event to the appropriate channel(s).
+     * Space-wide events go to all channels on the space.
+     * Channel-specific events go only to the matching channel.
+     * The `connected` event triggers a single resync for the whole space.
+     */
+    private routeSpaceEvent;
+    /**
+     * Handle reconnection for a space: fetch full state once, distribute to all channels.
+     */
+    private handleSpaceResync;
     /**
      * Handle a client-level event from the subscription.
-     * Channel events from the client SSE are ignored — they're handled by
-     * the space subscription via RoolSpace instead.
      * @internal
      */
     private handleClientEvent;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAMlD,OAAO,EAAE,WAAW,EAAoB,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EAKb,WAAW,EACX,UAAU,EACV,QAAQ,EAER,aAAa,EACb,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AASpB;;;;;;;;;;;GAWG;AACH,qBAAa,UAAW,SAAQ,YAAY,CAAC,gBAAgB,CAAC;IAC5D,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,IAAI,CAAe;IAC3B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,mBAAmB,CAA0C;IACrE,OAAO,CAAC,MAAM,CAAS;IAGvB,OAAO,CAAC,YAAY,CAAkC;IAGtD,OAAO,CAAC,kBAAkB,CAGrB;IAGL,OAAO,CAAC,cAAc,CAA0E;IAGhG,OAAO,CAAC,aAAa,CAA+B;IAGpD,OAAO,CAAC,YAAY,CAA4B;gBAEpC,MAAM,GAAE,gBAAqB;IAkDzC;;;;;OAKG;IACG,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IASpC;;;;OAIG;YACW,2BAA2B;IAQzC;;OAEG;IACH,OAAO,IAAI,IAAI;IAqBf;;;OAGG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5E;;;;OAIG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7E;;;;;;;OAOG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ7C;;OAEG;IACH,MAAM,IAAI,IAAI;IAed;;;OAGG;IACH,mBAAmB,IAAI,OAAO;IAI9B;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAIzC;;;;;;OAMG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IAW/D;;;OAGG;IACH,WAAW,IAAI,QAAQ;IAIvB;;;OAGG;IACH,IAAI,WAAW,IAAI,WAAW,GAAG,IAAI,CAEpC;IAMD;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAI5C;;;;;;;OAOG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAoD3E;;;;;;OAMG;IACG,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAgBpD;;;;OAIG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAmBnD;;;OAGG;IACG,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpF;;;OAGG;IACG,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAItE;;;OAGG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjD;;;;OAIG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,GAAG,OAAO,CAAC,SAAS,CAAC;IAepE;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC;IAM5C;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAI3D;;;;OAIG;IACG,iBAAiB,CAAC,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IActF;;;;OAIG;IACG,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,aAAa,CAAC;IAInG,sEAAsE;IAChE,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD,0CAA0C;IACpC,cAAc,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAIhD,yEAAyE;IACnE,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAQ1E;;;OAGG;IACG,cAAc,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC;IAIxF;;;;;OAKG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIhG,gEAAgE;IAC1D,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD,2DAA2D;IACrD,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ7D;;;OAGG;IACH,cAAc,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAIvD;;;;;OAKG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAqBjD;;OAEG;IACH,iBAAiB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAQ5C,OAAO,KAAK,WAAW,GAMtB;IAMD,OAAO,KAAK,gBAAgB,GAK3B;IAMD;;;;;OAKG;YACW,gBAAgB;IAmB9B;;;OAGG;IACH,OAAO,CAAC,WAAW;IAWnB;;;;OAIG;IACH,MAAM,CAAC,UAAU,IAAI,MAAM;IAI3B;;;OAGG;IACG,QAAQ,CAAC,CAAC,EACd,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC;IAQb,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,iBAAiB;IAkBzB;;;OAGG;IACH,OAAO,CAAC,YAAY;IAYpB;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAqB/B;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAuBvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA+BzB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IA0EzB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAOxB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAIxB;;;;OAIG;IACH,OAAO,CAAC,wBAAwB;CAejC"}

package/dist/client.js

@@ -4,16 +4,16 @@
 import { EventEmitter } from './event-emitter.js';
 import { AuthManager } from './auth.js';
 import { GraphQLClient } from './graphql.js';
-import { ClientSubscriptionManager } from './subscription.js';
+import { ClientSubscriptionManager, SpaceSubscriptionManager } from './subscription.js';
 import { MediaClient } from './media.js';
 import { ExtensionsClient } from './apps.js';
-import { generateEntityId } from './channel.js';
+import { RoolChannel, generateEntityId } from './channel.js';
 import { RoolSpace } from './space.js';
 import { defaultLogger } from './logger.js';
 /**
  * Rool Client - Manages authentication, space lifecycle, and shared infrastructure.
  *
- * The client is lightweight - most operations happen on RoolSpace and RoolChannel instances.
+ * The client is lightweight - most operations happen on RoolChannel instances.
  *
  * Features:
  * - Authentication (login, logout, token management)
@@ -29,8 +29,12 @@ export class RoolClient extends EventEmitter {
     graphqlClient;
     subscriptionManager = null;
     logger;
-    // Open spaces (cached for reuse by openChannel)
-    openSpaces = new Map();
+    // Registry of open channels (for cleanup on logout/destroy)
+    openChannels = new Map();
+    // Shared space subscriptions: one SSE connection per space, shared by all channels
+    spaceSubscriptions = new Map();
+    // Cached space data: avoids redundant openSpaceFull calls when opening multiple channels
+    spaceDataCache = new Map();
     // User storage cache (synced to localStorage)
     _storageCache = {};
     // Current user (fetched during initialize)
@@ -109,10 +113,16 @@ export class RoolClient extends EventEmitter {
     destroy() {
         this.authManager.destroy();
         this.subscriptionManager?.destroy();
-        // Close all open spaces (which close their channels and subscriptions)
-        for (const space of this.openSpaces.values())
-            space.close();
-        this.openSpaces.clear();
+        // Close all open channels — snapshot first to avoid mutating during iteration
+        const channels = [...this.openChannels.values()];
+        for (const channel of channels)
+            channel.close();
+        this.openChannels.clear();
+        // Clean up space subscriptions
+        for (const sub of this.spaceSubscriptions.values())
+            sub.manager.destroy();
+        this.spaceSubscriptions.clear();
+        this.spaceDataCache.clear();
         this.removeAllListeners();
     }
     // ===========================================================================
@@ -154,10 +164,16 @@ export class RoolClient extends EventEmitter {
     logout() {
         this.authManager.logout();
         this.unsubscribe();
-        // Close all open spaces (which close their channels and subscriptions)
-        for (const space of this.openSpaces.values())
-            space.close();
-        this.openSpaces.clear();
+        // Close all open channels — snapshot first to avoid mutating during iteration
+        const channels = [...this.openChannels.values()];
+        for (const channel of channels)
+            channel.close();
+        this.openChannels.clear();
+        // Clean up space subscriptions
+        for (const sub of this.spaceSubscriptions.values())
+            sub.manager.destroy();
+        this.spaceSubscriptions.clear();
+        this.spaceDataCache.clear();
     }
     /**
      * Process auth callback from URL fragment.
@@ -213,70 +229,99 @@ export class RoolClient extends EventEmitter {
     }
     /**
      * Open a channel on a space.
-     * Convenience method that opens (or reuses) the space, then opens the channel.
+     * Fetches full space data, ensures the channel exists, and starts the
+     * shared space subscription if not already active.
      *
      * @param spaceId - The ID of the space
      * @param channelId - The channel ID (created if it doesn't exist)
      */
     async openChannel(spaceId, channelId) {
+        if (!channelId || channelId.length > 32 || !/^[a-zA-Z0-9_-]+$/.test(channelId)) {
+            throw new Error('channelId must be 1–32 characters containing only alphanumeric characters, hyphens, and underscores');
+        }
         // Ensure client subscription is active (for lifecycle events)
         void this.ensureSubscribed();
-        const space = await this.openSpace(spaceId);
-        return space.openChannel(channelId);
+        // Fetch full space data (cached per space to avoid redundant fetches)
+        const result = await this.getSpaceData(spaceId);
+        // Ensure channel exists — create if missing
+        let channelData = result.channels[channelId];
+        if (!channelData) {
+            try {
+                channelData = await this.graphqlClient.createChannel(spaceId, channelId);
+            }
+            catch {
+                // Race: another client may have created it. Re-fetch.
+                this.spaceDataCache.delete(spaceId);
+                const refreshed = await this.getSpaceData(spaceId);
+                channelData = refreshed.channels[channelId];
+                if (!channelData)
+                    throw new Error(`Failed to create channel "${channelId}"`);
+            }
+        }
+        const channel = new RoolChannel({
+            id: spaceId,
+            name: result.name,
+            role: result.role,
+            linkAccess: result.linkAccess,
+            userId: result.userId,
+            objectIds: result.objectIds,
+            objectStats: result.objectStats,
+            schema: result.schema,
+            meta: result.meta,
+            channel: channelData,
+            channelId,
+            graphqlClient: this.graphqlClient,
+            mediaClient: this.mediaClient,
+            logger: this.logger,
+            onClose: () => this.unregisterChannel(spaceId, channelId),
+        });
+        // Register for cleanup (before awaiting subscription so close() works if it fails)
+        this.registerChannel(spaceId, channelId, channel);
+        // Ensure shared space subscription is active
+        await this.ensureSpaceSubscription(spaceId);
+        return channel;
     }
     /**
-     * Open a space with a real-time subscription.
-     * Returns a live RoolSpace handle with channel lifecycle events.
-     * Reuses an existing handle if the space is already open.
+     * Open a space for admin operations.
+     * Returns a lightweight handle for user management, link access,
+     * channel management, and export. Does not start a real-time subscription.
      *
-     * Call space.close() when done to stop the subscription.
+     * To work with objects and AI, call space.openChannel(channelId).
      */
     async openSpace(spaceId) {
-        // Reuse existing open space
-        const existing = this.openSpaces.get(spaceId);
-        if (existing)
-            return existing;
-        // Ensure client subscription is active (for lifecycle events)
-        void this.ensureSubscribed();
-        const fullData = await this.graphqlClient.openSpaceFull(spaceId);
-        const space = new RoolSpace({
+        const { name, role, linkAccess, memberCount, channels } = await this.graphqlClient.openSpace(spaceId);
+        return new RoolSpace({
             id: spaceId,
-            name: fullData.name,
-            role: fullData.role,
-            userId: fullData.userId,
-            linkAccess: fullData.linkAccess,
-            memberCount: fullData.memberCount,
-            fullData,
+            name,
+            role: role,
+            linkAccess,
+            memberCount,
+            channels,
             graphqlClient: this.graphqlClient,
             mediaClient: this.mediaClient,
-            authManager: this.authManager,
-            graphqlUrl: this.urls.graphql,
-            logger: this.logger,
-            onClose: () => this.openSpaces.delete(spaceId),
-        });
-        this.openSpaces.set(spaceId, space);
-        // Forward space channel events to client-level events (backwards compat)
-        space.on('channelCreated', (channel) => {
-            this.emit('channelCreated', spaceId, channel);
-        });
-        space.on('channelUpdated', (channel) => {
-            this.emit('channelUpdated', spaceId, channel);
+            openChannelFn: (sid, cid) => this.openChannel(sid, cid),
         });
-        space.on('channelDeleted', (channelId) => {
-            this.emit('channelDeleted', spaceId, channelId);
-        });
-        return space;
     }
     /**
      * Create a new space.
-     * Returns a RoolSpace handle with a real-time subscription.
+     * Returns a RoolSpace handle for admin operations.
      * Call space.openChannel(channelId) to start working with objects.
      */
     async createSpace(name) {
         // Ensure client subscription is active (for lifecycle events)
         void this.ensureSubscribed();
         const { spaceId } = await this.graphqlClient.createSpace(name);
-        return this.openSpace(spaceId);
+        return new RoolSpace({
+            id: spaceId,
+            name,
+            role: 'owner',
+            linkAccess: 'none',
+            memberCount: 1,
+            channels: [],
+            graphqlClient: this.graphqlClient,
+            mediaClient: this.mediaClient,
+            openChannelFn: (sid, cid) => this.openChannel(sid, cid),
+        });
     }
     /**
      * Rename a channel in a space.
@@ -298,12 +343,6 @@ export class RoolClient extends EventEmitter {
      */
     async deleteSpace(spaceId) {
         await this.graphqlClient.deleteSpace(spaceId);
-        // Close and remove the cached space if open
-        const space = this.openSpaces.get(spaceId);
-        if (space) {
-            space.close();
-            this.openSpaces.delete(spaceId);
-        }
         // Client-level event will be emitted via SSE subscription
     }
     /**
@@ -465,6 +504,7 @@ export class RoolClient extends EventEmitter {
     /**
      * Ensure the client-level event subscription is active.
      * Called automatically when opening spaces.
+     * Also fetches and caches the current user ID.
      * @internal
      */
     async ensureSubscribed() {
@@ -513,12 +553,125 @@ export class RoolClient extends EventEmitter {
         return this.graphqlClient.query(query, variables);
     }
     // ===========================================================================
+    // Private Methods - Channel Registry
+    // ===========================================================================
+    registerChannel(spaceId, channelId, channel) {
+        this.openChannels.set(`${spaceId}:${channelId}`, channel);
+    }
+    unregisterChannel(spaceId, channelId) {
+        this.openChannels.delete(`${spaceId}:${channelId}`);
+        // Tear down space subscription if no more channels on this space
+        const hasChannelsOnSpace = [...this.openChannels.keys()].some(key => key.startsWith(`${spaceId}:`));
+        if (!hasChannelsOnSpace) {
+            const sub = this.spaceSubscriptions.get(spaceId);
+            if (sub) {
+                sub.manager.destroy();
+                this.spaceSubscriptions.delete(spaceId);
+            }
+        }
+    }
+    // ===========================================================================
+    // Private Methods - Space Subscriptions
+    // ===========================================================================
+    /**
+     * Get space data, using a short-lived cache so concurrent openChannel calls
+     * for the same space share one fetch.
+     */
+    getSpaceData(spaceId) {
+        const cached = this.spaceDataCache.get(spaceId);
+        if (cached)
+            return cached;
+        const promise = this.graphqlClient.openSpaceFull(spaceId).finally(() => {
+            // Clear cache once resolved — data is now in the channels and kept current via SSE
+            this.spaceDataCache.delete(spaceId);
+        });
+        this.spaceDataCache.set(spaceId, promise);
+        return promise;
+    }
+    /**
+     * Ensure a shared space subscription exists for the given spaceId.
+     * Creates one if it doesn't exist yet. Returns when connected.
+     */
+    ensureSpaceSubscription(spaceId) {
+        const existing = this.spaceSubscriptions.get(spaceId);
+        if (existing)
+            return existing.ready;
+        const manager = new SpaceSubscriptionManager({
+            graphqlUrl: this.urls.graphql,
+            authManager: this.authManager,
+            logger: this.logger,
+            spaceId,
+            onEvent: (event) => this.routeSpaceEvent(spaceId, event),
+            onConnectionStateChanged: () => { },
+            onError: (error) => {
+                this.logger.error(`[RoolClient] Space ${spaceId} subscription error:`, error);
+            },
+        });
+        const ready = manager.subscribe();
+        this.spaceSubscriptions.set(spaceId, { manager, ready });
+        return ready;
+    }
+    /**
+     * Route a space event to the appropriate channel(s).
+     * Space-wide events go to all channels on the space.
+     * Channel-specific events go only to the matching channel.
+     * The `connected` event triggers a single resync for the whole space.
+     */
+    routeSpaceEvent(spaceId, event) {
+        // Reconnect or full state change: single fetch, distribute to all channels
+        if (event.type === 'connected' || event.type === 'space_changed') {
+            this.handleSpaceResync(spaceId);
+            return;
+        }
+        // Channel-specific events: route to the matching channel only
+        if ('channelId' in event && event.channelId) {
+            const channel = this.openChannels.get(`${spaceId}:${event.channelId}`);
+            if (channel)
+                channel._handleEvent(event);
+            return;
+        }
+        // Space-wide events (objects, schema, metadata, space_changed):
+        // broadcast to all channels on this space
+        for (const [key, channel] of this.openChannels) {
+            if (key.startsWith(`${spaceId}:`)) {
+                channel._handleEvent(event);
+            }
+        }
+    }
+    /**
+     * Handle reconnection for a space: fetch full state once, distribute to all channels.
+     */
+    handleSpaceResync(spaceId) {
+        // Collect channels on this space
+        const channels = [];
+        for (const [key, channel] of this.openChannels) {
+            if (key.startsWith(`${spaceId}:`))
+                channels.push(channel);
+        }
+        if (channels.length === 0)
+            return;
+        this.logger.info(`[RoolClient] Space ${spaceId} reconnected, resyncing ${channels.length} channel(s)...`);
+        void this.graphqlClient.openSpaceFull(spaceId).then((result) => {
+            for (const channel of channels) {
+                const channelData = result.channels[channel.channelId];
+                channel._applyResyncData({
+                    meta: result.meta,
+                    schema: result.schema,
+                    objectIds: result.objectIds,
+                    objectStats: result.objectStats,
+                    channel: channelData,
+                });
+            }
+            this.logger.info(`[RoolClient] Space ${spaceId} resync complete (${result.objectIds.length} objects)`);
+        }).catch((error) => {
+            this.logger.error(`[RoolClient] Space ${spaceId} resync failed:`, error);
+        });
+    }
+    // ===========================================================================
     // Private Methods - Event Handling
     // ===========================================================================
     /**
      * Handle a client-level event from the subscription.
-     * Channel events from the client SSE are ignored — they're handled by
-     * the space subscription via RoolSpace instead.
      * @internal
      */
     handleClientEvent(event) {
@@ -563,10 +716,24 @@ export class RoolClient extends EventEmitter {
             case 'user_storage_changed':
                 this.handleUserStorageChanged(event.key, event.value);
                 break;
-            // Channel events from client SSE are ignored — handled by RoolSpace
             case 'channel_created':
+                this.emit('channelCreated', event.spaceId, {
+                    id: event.channelId,
+                    name: event.name ?? null,
+                    createdAt: event.channelCreatedAt ?? Date.now(),
+                    createdBy: event.channelCreatedBy ?? '',
+                    createdByName: event.channelCreatedByName ?? null,
+                    interactionCount: 0,
+                    extensionUrl: event.channelExtensionUrl ?? null,
+                    extensionId: event.channelExtensionId ?? null,
+                    manifest: event.channelManifest ?? null,
+                });
+                break;
             case 'channel_renamed':
+                this.emit('channelRenamed', event.spaceId, event.channelId, event.name);
+                break;
             case 'channel_deleted':
+                this.emit('channelDeleted', event.spaceId, event.channelId);
                 break;
         }
     }