docs: deprecate the legacy window-global connection handoff

Author: antfubot

packages/devframe/src/client/connection-storage.ts

@@ -2,7 +2,20 @@ import type { ConnectionMeta } from 'devframe/types'
 import type { DevframeConnection } from './connection'
 import { DEVFRAME_CONNECTION_KEY } from 'devframe/constants'
 
+/**
+ * @deprecated Legacy window-global meta handoff, fully subsumed by the
+ * connection stored under `DEVFRAME_CONNECTION_KEY` (which carries the meta
+ * together with its source URL and auth token). Still written and read for
+ * compatibility with viewers bundling an older `devframe/client`; the read
+ * path goes first, then the writes, in future releases.
+ */
 const CONNECTION_META_KEY = '__DEVFRAME_CONNECTION_META__'
+/**
+ * Key for the persisted auth token. The `localStorage` entry stays — it is
+ * what lets trust survive reloads and reach sibling tabs. The *window-global*
+ * entry under this key is deprecated: same-realm viewers read the token from
+ * the connection under `DEVFRAME_CONNECTION_KEY` instead.
+ */
 const CONNECTION_AUTH_TOKEN_KEY = '__DEVFRAME_CONNECTION_AUTH_TOKEN__'
 
 function readFromWindows<T>(key: string): T | undefined {
@@ -26,6 +39,12 @@ export function readStoredConnection(): DevframeConnection | undefined {
   return readFromWindows<DevframeConnection>(DEVFRAME_CONNECTION_KEY)
 }
 
+/**
+ * @deprecated Reads the legacy meta global, kept only so a viewer embedded
+ * under a host running an older `devframe/client` still inherits a
+ * connection. Use {@link readStoredConnection} — `DEVFRAME_CONNECTION_KEY`
+ * is the authoritative handoff.
+ */
 export function readStoredConnectionMeta(): (ConnectionMeta & { baseUrl?: string }) | undefined {
   return readFromWindows<ConnectionMeta & { baseUrl?: string }>(CONNECTION_META_KEY)
 }
@@ -41,13 +60,18 @@ export function readStoredAuthToken(userAuthToken?: string): string | undefined
   }
   catch {}
 
+  // Deprecated window-global fallback — an older `devframe/client` host may
+  // still publish the token this way. New hosts hand it over inside the
+  // connection under `DEVFRAME_CONNECTION_KEY`.
   return readFromWindows<string>(CONNECTION_AUTH_TOKEN_KEY)
 }
 
 export function storeConnection(connection: DevframeConnection): void {
   ;(globalThis as any)[DEVFRAME_CONNECTION_KEY] = connection
-  // Keep the established metadata/auth globals in sync for viewers that still
-  // consume the legacy handoff directly.
+  // Deprecated: mirror into the legacy meta global so viewers bundling an
+  // older `devframe/client` still inherit a connection. The connection under
+  // `DEVFRAME_CONNECTION_KEY` is authoritative; this write goes away once the
+  // legacy read path is retired.
   ;(globalThis as any)[CONNECTION_META_KEY] = {
     ...connection.connectionMeta,
     baseUrl: connection.metaBaseUrl,
@@ -61,6 +85,9 @@ export function storeAuthToken(token: string): void {
     localStorage.setItem(CONNECTION_AUTH_TOKEN_KEY, token)
   }
   catch {}
+  // Deprecated: mirror into the legacy window global for viewers bundling an
+  // older `devframe/client`. New viewers read the token from the connection
+  // under `DEVFRAME_CONNECTION_KEY`.
   ;(globalThis as any)[CONNECTION_AUTH_TOKEN_KEY] = token
 
   const connection = readStoredConnection()

packages/devframe/src/constants.ts

@@ -9,6 +9,11 @@ export const DEVFRAME_CONNECTION_META_FILENAME = '__connection.json'
  * Global key holding the serializable connection prepared by
  * `setupDevframeConnection()`. External viewers can use this key to read the
  * connection from another JavaScript realm.
+ *
+ * This is the authoritative same-realm handoff: it supersedes the legacy
+ * `__DEVFRAME_CONNECTION_META__` and window-global
+ * `__DEVFRAME_CONNECTION_AUTH_TOKEN__` entries, which are now deprecated and
+ * kept in sync only for viewers bundling an older `devframe/client`.
  */
 export const DEVFRAME_CONNECTION_KEY = '__DEVFRAME_CONNECTION__'