refactor(client): name connection discovery options and explain isolation

Author: dvcolomban

packages/devframe/src/client/connection.ts

@@ -23,18 +23,33 @@ export interface DevframeConnection {
   metaBaseUrl: string
   /** Previously issued bearer token, when the connection is already trusted. */
   authToken?: string
-  /** Skip shared browser caches and authentication broadcasts. Retained when reconnecting. */
+  /**
+   * Skip shared browser caches and authentication broadcasts. Retained when reconnecting.
+   * The origin-wide `devframe-auth` channel carries no backend identity, so a token
+   * from another connection could otherwise overwrite this connection's credentials.
+   * Authentication still uses this connection's own RPC transport.
+   */
+  isolated?: boolean
+}
+
+/**
+ * Configure discovery before metadata and its source URL have been resolved.
+ * Shared behavior is the default. Set `isolated: true` when connecting to independent
+ * backends from one viewer. Browser credential caches are not scoped per backend, and
+ * `devframe-auth` broadcasts carry no backend identity, so they can mix credentials.
+ * An isolated connection still authenticates through its own RPC transport.
+ */
+export interface DevframeConnectionDiscoveryOptions {
+  /** Use connection-local credentials; see {@link DevframeConnection.isolated}. Defaults to shared behavior. */
   isolated?: boolean
+  connectionMeta?: never
+  metaBaseUrl?: never
+  authToken?: never
 }
 
 export interface SetupDevframeConnectionOptions {
   /** Reuse a prepared connection, or configure isolation before resolving its metadata. */
-  connection?: DevframeConnection | {
-    isolated?: boolean
-    connectionMeta?: never
-    metaBaseUrl?: never
-    authToken?: never
-  }
+  connection?: DevframeConnection | DevframeConnectionDiscoveryOptions
   /** Use a pre-known descriptor while deriving its source URL from `baseURL`. */
   connectionMeta?: ConnectionMeta
   /** Base URL, or fallback list, used to locate `__connection.json`. */

packages/devframe/src/client/rpc.ts

@@ -425,7 +425,10 @@ export async function getDevframeRpcClient(
           wsOptions: options.wsOptions,
         })
 
-  /** Channel name kept for cross-tab interop with the Vite DevTools auth page. */
+  /**
+   * Shared with the Vite DevTools auth page; messages carry no backend identity,
+   * so isolated connections must neither publish nor consume credentials here.
+   */
   let authChannel: BroadcastChannel | undefined
   if (!connection.isolated) {
     try {

tests/__snapshots__/tsnapi/devframe/client.snapshot.d.ts

@@ -8,6 +8,12 @@ export interface DevframeConnection {
   authToken?: string;
   isolated?: boolean;
 }
+export interface DevframeConnectionDiscoveryOptions {
+  isolated?: boolean;
+  connectionMeta?: never;
+  metaBaseUrl?: never;
+  authToken?: never;
+}
 export interface DevframeRpcClient {
   events: EventEmitter<RpcClientEvents>;
   readonly isTrusted: boolean | null;
@@ -126,12 +132,7 @@ export interface RpcStreamingClientHost {
   upload: <T = unknown>(_: string, _: string) => StreamSink<T>;
 }
 export interface SetupDevframeConnectionOptions {
-  connection?: DevframeConnection | {
-    isolated?: boolean;
-    connectionMeta?: never;
-    metaBaseUrl?: never;
-    authToken?: never;
-  };
+  connection?: DevframeConnection | DevframeConnectionDiscoveryOptions;
   connectionMeta?: ConnectionMeta;
   baseURL?: string | string[];
   authToken?: string;