docs(client): trim the embed comments to the load-bearing ones

Author: amitbardos

src/client.ts

@@ -96,9 +96,7 @@ export function createClient(config: CreateClientConfig): Base44Client {
 
   const embedOtt = takeEmbedTokenFromUrl();
 
-  // Asked again on every use, so a session that arrives later — from the
-  // exchange, or from a login — reaches the socket and every other module.
-  // A declaration, not a const, so this block can stay above the auth module.
+  // A declaration, not a const: this block sits above the auth module.
   function getToken(): string | null {
     return userAuthModule.getToken() ?? (embedOtt ? null : getAccessToken());
   }
@@ -122,9 +120,8 @@ export function createClient(config: CreateClientConfig): Base44Client {
     return socket;
   };
 
-  // Apps read getAccessToken() as they load and pass the result in as `token`,
-  // so on an embedded load this is the OTT: proof of an identity, not one to
-  // send as a bearer. The exchange below is what turns it into a session.
+  // Apps pass getAccessToken() in as `token`, which in a frame is the OTT —
+  // what the exchange trades for a session, never a bearer itself.
   const token = embedOtt ? undefined : config.token;
 
   const headers = {
@@ -192,9 +189,8 @@ export function createClient(config: CreateClientConfig): Base44Client {
       serverUrl,
       token,
       embedded: Boolean(embedOtt),
-      // The socket carries its token on the handshake, so an identity change
-      // only reaches it by opening a new connection — or, on logout, by
-      // dropping the one still running as the user who just left.
+      // The socket carries its token on the handshake, so it can only pick a
+      // new one up by redialling — or, on logout, by dropping what it has.
       onSessionChange: (hasSession) =>
         hasSession ? socket?.reconnect() : socket?.disconnect(),
     }
@@ -204,8 +200,7 @@ export function createClient(config: CreateClientConfig): Base44Client {
   // requests during construction (notably analytics, which fires an init
   // event whose flush calls auth.me()). Without this, the first User/me
   // request is built before setToken runs and goes out unauthenticated.
-  // Not in a frame: a stored token there belongs to an earlier visitor, not to
-  // this session, which only the exchange below can produce.
+  // Not in a frame: a stored token there belongs to an earlier visitor.
   if (typeof window !== "undefined" && !embedOtt) {
     const accessToken = token || getAccessToken();
     if (accessToken) {
@@ -217,18 +212,15 @@ export function createClient(config: CreateClientConfig): Base44Client {
     ? exchangeEmbedToken({ serverUrl, appId, ott: embedOtt })
     : null;
 
-  // Settles once the exchanged session is applied (memory only); at once
-  // otherwise. Never rejects: every request waits on it, so a failure here
-  // must not turn into a rejection on each of them.
+  // Never rejects: every request waits on it, so one failure here must not
+  // become a rejection on each of them.
   const authReady: Promise<void> = session
     ? session
         .then((sessionToken) => {
           if (sessionToken) {
             userAuthModule.setToken(sessionToken, false);
             return;
           }
-          // The app is about to run anonymous. Say why, once, instead of
-          // leaving only the 401s that follow.
           const error = new Error(
             "Base44: the embed token was refused, so this app is not signed in.",
           );
@@ -241,8 +233,8 @@ export function createClient(config: CreateClientConfig): Base44Client {
     : Promise.resolve();
 
   if (session) {
-    // Requests issued during the exchange wait for it. Registered after createAxiosClient's
-    // interceptors so it runs first and the anonymous-visitor header sees the Authorization.
+    // Registered after createAxiosClient's so it runs first (axios unshifts),
+    // letting the anonymous-visitor header see the Authorization we just set.
     for (const client of [axiosClient, functionsAxiosClient]) {
       client.interceptors.request.use(async (requestConfig) => {
         await authReady;
@@ -316,8 +308,7 @@ export function createClient(config: CreateClientConfig): Base44Client {
       getSocket,
       appId,
       serverUrl,
-      // Read synchronously, unlike everything else: these build a URL rather
-      // than issue a request, so during the exchange they see no token.
+      // Sync, unlike everything else: these return a URL, not a promise.
       getToken,
     }),
     aiGateway: createAiGatewayModule({ serverUrl, getToken, appId }),
@@ -366,9 +357,8 @@ export function createClient(config: CreateClientConfig): Base44Client {
       getSocket,
       appId,
       serverUrl,
-      // The user's token, as on the user-scoped module: the only thing this is
-      // read for is the `?token=` on a channel URL handed to that user, which
-      // the app's service credential must never end up in.
+      // The user's token, deliberately: this is read only for the `?token=` on
+      // a channel URL handed to that user. Never the service credential.
       getToken,
     }),
     aiGateway: createAiGatewayModule({