@ai4b-team/fsaos-gateway-sdk 3.34.0 → 3.34.2

package/dist/index.cjs

@@ -101,6 +101,7 @@ __export(src_exports, {
   initSession: () => initSession,
   initVfsRealtimeWs: () => initVfsRealtimeWs,
   initializeFsaos: () => initializeFsaos,
+  initializeWorkspace: () => initializeWorkspace,
   interpretSchema: () => interpretSchema,
   invalidateAllVfs: () => invalidateAllVfs,
   invalidateChannelMessages: () => invalidateChannelMessages,
@@ -116,6 +117,7 @@ __export(src_exports, {
   isScopeReady: () => isScopeReady,
   itemsFilterFromQueryFilter: () => itemsFilterFromQueryFilter,
   listChildren: () => listChildren,
+  loadMounts: () => loadMounts,
   mount: () => mount2,
   mountRealtimeScope: () => mountRealtimeScope,
   normalizeItem: () => normalizeItem,
@@ -127,9 +129,11 @@ __export(src_exports, {
   readItem: () => readItem,
   refreshQuery: () => refreshQuery,
   registerCleanup: () => registerCleanup,
+  replaceMounts: () => replaceMounts,
   resetAllSdkState: () => resetAllSdkState,
   resolvePrincipalId: () => resolvePrincipalId,
   resubscribePath: () => resubscribePath,
+  selectMount: () => selectMount,
   serverDeadlinePassed: () => serverDeadlinePassed,
   serverMsUntil: () => serverMsUntil,
   serverNow: () => serverNow,
@@ -335,7 +339,7 @@ function notifyAnchorListeners() {
 }
 function setAnchor(ref) {
   const path = typeof ref === "string" ? ref : ref.path;
-  const changed = currentAnchorPath !== path;
+  const changed = currentAnchorPath !== path || currentAnchorRef?.id !== (typeof ref === "string" ? void 0 : ref.id);
   currentAnchorPath = path;
   currentAnchorRef = typeof ref === "string" ? null : ref;
   if (typeof ref !== "string" && !mountSet.some((m) => m.id === ref.id)) {
@@ -372,13 +376,13 @@ function isAnchorReady() {
   return anchorResolved;
 }
 var homeAnchor = null;
-function electHomeAnchor(ref) {
+function electHomeAnchor(ref, options = {}) {
   if (homeAnchor) {
     console.warn("[SDK] electHomeAnchor called twice; ignoring (logout to re-elect).");
     return;
   }
   homeAnchor = ref;
-  setAnchor(ref);
+  if (options.activate !== false) setAnchor(ref);
 }
 function getHomeAnchor() {
   return homeAnchor;
@@ -408,32 +412,33 @@ function subscribeMounts(listener) {
     mountListeners.delete(listener);
   };
 }
-function setMountsState(mounts) {
+function commitMountSelection(mounts, anchor) {
+  const mountsChanged = JSON.stringify(mountSet) !== JSON.stringify(mounts);
+  const anchorChanged = currentAnchorPath !== anchor.path || currentAnchorRef?.id !== anchor.id;
   mountSet = mounts;
-  notifyMountListeners();
-}
-function addMountState(ref) {
-  if (mountSet.some((m) => m.id === ref.id)) return;
-  mountSet = [...mountSet, ref];
-  notifyMountListeners();
-}
-function removeMountState(id) {
-  const removed = mountSet.find((m) => m.id === id);
-  if (!removed) return;
-  mountSet = mountSet.filter((m) => m.id !== id);
-  notifyMountListeners();
-  if (currentAnchorRef?.id === id && homeAnchor) {
-    setAnchor(homeAnchor);
+  currentAnchorPath = anchor.path;
+  currentAnchorRef = anchor;
+  if (!anchorResolved) {
+    anchorResolved = true;
+    resolveAnchorReady();
   }
+  if (mountsChanged) notifyMountListeners();
+  if (anchorChanged) notifyAnchorListeners();
 }
 var sessionEntry = null;
 var sessionPromise = null;
+var sessionGeneration = 0;
+function getSessionGeneration() {
+  return sessionGeneration;
+}
 async function initSession() {
   if (sessionEntry) return sessionEntry;
   if (sessionPromise) return sessionPromise;
+  const generation = sessionGeneration;
   sessionPromise = (async () => {
     const hostname = getHostname();
     const token = await getAccessToken();
+    if (generation !== sessionGeneration) throw new Error("Session changed during initialization");
     const headers = {};
     if (token) {
       headers["Authorization"] = `Bearer ${token}`;
@@ -446,6 +451,7 @@ async function initSession() {
       throw new Error(`Session init failed: ${response.status} ${response.statusText}`);
     }
     const json = await response.json();
+    if (generation !== sessionGeneration) throw new Error("Session changed during initialization");
     const entry = json.entry || json;
     sessionEntry = {
       scope_id: entry.scope_id,
@@ -459,13 +465,17 @@ async function initSession() {
       principal_id: entry.principal_id || null
     };
     return sessionEntry;
-  })();
+  })().catch((error) => {
+    if (generation === sessionGeneration) sessionPromise = null;
+    throw error;
+  });
   return sessionPromise;
 }
 function getSessionEntry() {
   return sessionEntry;
 }
 function clearSession() {
+  sessionGeneration++;
   sessionEntry = null;
   sessionPromise = null;
   currentAnchorPath = null;
@@ -480,6 +490,7 @@ function registerCleanup(fn) {
 function resetAllSdkState() {
   clearSession();
   clearCachedToken();
+  resolveAnchorReady();
   anchorResolved = false;
   anchorReady = new Promise((resolve) => {
     resolveAnchorReady = resolve;
@@ -572,24 +583,28 @@ var GatewayRequestError = class extends Error {
   }
 };
 async function gatewayCall(method, params = {}) {
+  const generation = getSessionGeneration();
+  const requestedAnchor = getAnchor();
   const hostname = getHostname();
   const url = `${GATEWAY_URL}/d/${hostname}`;
   const headers = {
     "Content-Type": "application/json"
   };
   const token = await getAccessToken();
+  if (generation !== getSessionGeneration()) throw new Error("Session changed before gateway request");
   if (token) {
     headers["Authorization"] = `Bearer ${token}`;
   }
   if (!ANCHOR_INDEPENDENT_METHODS.has(method) && !params._scope_path) {
     await awaitAnchorReady();
   }
+  if (generation !== getSessionGeneration()) throw new Error("Session changed before gateway request");
   const enrichedParams = { ...params };
   const session = getSessionEntry();
   if (!enrichedParams.domain_scope_id && session?.scope_id) {
     enrichedParams.domain_scope_id = session.scope_id;
   }
-  const anchorPath = getAnchor();
+  const anchorPath = requestedAnchor ?? getAnchor();
   if (!enrichedParams._scope_path && anchorPath) {
     enrichedParams._scope_path = anchorPath;
   }
@@ -599,6 +614,7 @@ async function gatewayCall(method, params = {}) {
     body: JSON.stringify({ method, params: enrichedParams })
   });
   const responseBody = await response.text();
+  if (generation !== getSessionGeneration()) throw new Error("Session changed during gateway request");
   let json = null;
   if (responseBody) {
     try {
@@ -705,6 +721,11 @@ function clearArrangementRefreshes(client2) {
   pending.delete(client2);
 }
 var client = null;
+registerCleanup(() => {
+  if (!client) return;
+  void client.cancelQueries({ queryKey: ["vfs"] });
+  client.removeQueries({ queryKey: ["vfs"] });
+});
 function setQueryClient(custom) {
   if (client && client !== custom) {
     throw new Error(
@@ -1982,60 +2003,40 @@ function invalidateOpenEnvelope(path, strategy) {
   }
 }
 
-// src/mounts.ts
-function declPath(memberSpacePath) {
-  return `${memberSpacePath}/settings/mounts`;
-}
-var declItemPath = null;
-async function loadMounts(memberSpacePath, resolveRef) {
-  declItemPath = declPath(memberSpacePath);
-  try {
-    const res = await gatewayCall("read", { path: declItemPath });
-    const ids = res?.item?.type_data?.mounts ?? [];
-    const refs = ids.map(resolveRef).filter((r) => r !== null);
-    const home = getHomeAnchor();
-    if (home && !refs.some((r) => r.id === home.id)) {
-      refs.unshift(home);
-    }
-    setMountsState(refs);
-    return refs;
-  } catch {
-    const home = getHomeAnchor();
-    const refs = home ? [home] : [];
-    setMountsState(refs);
-    return refs;
-  }
-}
-async function persist() {
-  if (!declItemPath) return;
-  const ids = getMounts().map((m) => m.id);
-  const lastAnchor = getAnchorRef()?.id ?? null;
-  try {
-    await gatewayCall("update", {
-      path: declItemPath,
-      type_data: { mounts: ids, last_anchor: lastAnchor }
-    });
-  } catch (e) {
-    try {
-      const parent = declItemPath.split("/").slice(0, -1).join("/");
-      await gatewayCall("create", {
-        parent_path: parent,
-        name: "mounts",
-        item_type: "file",
-        type_data: { mounts: ids, last_anchor: lastAnchor }
-      });
-    } catch (e2) {
-      console.warn("[SDK] mount declaration persist failed:", e2);
-    }
-  }
-}
-async function mount(ref) {
-  addMountState(ref);
-  await persist();
+// src/memberships.ts
+function membershipToMountRef(m) {
+  return {
+    id: m.accountId,
+    path: m.path,
+    kind: m.isSpace ? "space" : "account",
+    name: m.name,
+    grantedUnderAccountId: m.grantedUnderAccountId ?? void 0
+  };
 }
-async function unmount(id) {
-  removeMountState(id);
-  await persist();
+async function fetchMemberships() {
+  const result = await gatewayCall("list-memberships", {});
+  const memberships = result.memberships || [];
+  return memberships.map((m) => ({
+    accountId: m.account_id,
+    path: m.account_path,
+    name: m.account_name,
+    role: m.role || "member",
+    typeData: m.account_type_data || {},
+    joinedAt: m.joined_at,
+    via: m.via,
+    placement: m.placement,
+    subordinateTo: m.subordinate_to ?? null,
+    cascadeAnchorId: m.cascade_anchor_id ?? null,
+    isAccount: m.is_account ?? void 0,
+    isSpace: m.is_space ?? void 0,
+    isOwner: m.is_owner ?? void 0,
+    billingResponsible: m.billing_responsible ?? void 0,
+    grantedVia: m.granted_via ?? null,
+    grantedUnderAccountId: m.granted_under_account_id ?? null,
+    membershipPath: m.membership_path ?? null,
+    personalSpaceId: m.personal_space_id ?? null,
+    personalSpacePath: m.personal_space_path ?? null
+  }));
 }
 
 // src/vfs-realtime-ws.ts
@@ -2045,7 +2046,10 @@ var unsubCcmEvents = null;
 var debounceTimers = /* @__PURE__ */ new Map();
 var DEBOUNCE_MS = 250;
 function initVfsRealtimeWs(accountId) {
-  disposeVfsRealtimeWs();
+  if (unsubEvents) {
+    mountRealtimeScope(accountId);
+    return;
+  }
   mountRealtimeScope(accountId);
   unsubEvents = subscribeToEvents(
     "vfs_change",
@@ -2162,6 +2166,147 @@ function applyInvalidation(action, path, data, parentPath) {
   }
 }
 
+// src/mounts.ts
+var declaration = null;
+registerCleanup(() => {
+  declaration = null;
+});
+function assertCurrent(owner) {
+  if (owner !== declaration || owner.generation !== getSessionGeneration()) throw new Error("Workspace session changed");
+}
+function missing(error) {
+  return error instanceof GatewayRequestError && error.payload?.error === "item_not_found";
+}
+function canonical(owner, ref) {
+  const current = owner.resolve(ref.id);
+  if (!current || current.path !== ref.path || current.kind !== ref.kind) {
+    throw new Error("Mount is not an available membership");
+  }
+  return current;
+}
+function withHome(refs) {
+  const home = getHomeAnchor();
+  if (!home) throw new Error("Elect a home account before loading mounts");
+  return [home, ...refs.filter((ref, index) => ref.id !== home.id && refs.findIndex((r) => r.id === ref.id) === index)];
+}
+function signature(refs, anchor) {
+  return JSON.stringify({ mounts: refs.map((ref) => ref.id), last_anchor: anchor.id });
+}
+async function save(owner, refs, anchor) {
+  assertCurrent(owner);
+  const next = signature(refs, anchor);
+  if (owner.saved === next) return;
+  const type_data = JSON.parse(next);
+  await gatewayCall(owner.exists ? "update" : "create", owner.exists ? {
+    _scope_path: owner.scope,
+    path: owner.path,
+    type_data
+  } : {
+    _scope_path: owner.scope,
+    parent_path: owner.path.slice(0, owner.path.lastIndexOf("/")),
+    name: "mounts",
+    item_type: "file",
+    type_data
+  });
+  assertCurrent(owner);
+  owner.exists = true;
+  owner.saved = next;
+}
+function publish(refs, anchor) {
+  const previous = getMounts();
+  initVfsRealtimeWs(getHomeAnchor().id);
+  for (const ref of previous) if (!refs.some((r) => r.id === ref.id)) unmountRealtimeScope(ref.id);
+  for (const ref of refs) mountRealtimeScope(ref.id);
+  commitMountSelection(refs, anchor);
+}
+async function loadMounts(memberSpacePath, resolveRef, options = {}) {
+  const home = getHomeAnchor();
+  if (!home) throw new Error("Elect a home account before loading mounts");
+  const path = `${memberSpacePath}/settings/mounts`;
+  if (declaration && declaration.path !== path) throw new Error("Reset the session before changing the mount declaration owner");
+  const owner = declaration ??= {
+    generation: getSessionGeneration(),
+    path,
+    scope: home.path,
+    resolve: resolveRef,
+    exists: false,
+    ready: false,
+    saved: null,
+    queue: Promise.resolve()
+  };
+  assertCurrent(owner);
+  if (owner.loading) return owner.loading;
+  if (owner.ready) return getMounts();
+  owner.resolve = resolveRef;
+  owner.loading = (async () => {
+    let data = null;
+    try {
+      const response = await gatewayCall("read", { path, _scope_path: owner.scope });
+      assertCurrent(owner);
+      data = response.type_data ?? response.item?.type_data;
+      if (!data || !Array.isArray(data.mounts) || !data.mounts.every((id) => typeof id === "string")) {
+        throw new Error("Invalid saved mount declaration");
+      }
+      owner.exists = true;
+    } catch (error) {
+      assertCurrent(owner);
+      if (!missing(error)) throw error;
+      owner.exists = false;
+    }
+    const initial = options.initialAnchor ? canonical(owner, options.initialAnchor) : home;
+    const refs = withHome(data ? data.mounts.map(resolveRef).filter((ref) => ref !== null) : [initial]);
+    const anchor = data ? refs.find((ref) => ref.id === data.last_anchor) ?? refs.find((ref) => ref.kind === "space") ?? home : initial;
+    if (data) owner.saved = signature(refs, anchor);
+    else if (options.initialAnchor) await save(owner, refs, anchor);
+    assertCurrent(owner);
+    owner.ready = true;
+    publish(refs, anchor);
+    return refs;
+  })().finally(() => {
+    owner.loading = void 0;
+  });
+  return owner.loading;
+}
+function mutate(change) {
+  const owner = declaration;
+  if (!owner?.ready) return Promise.reject(new Error("Workspace mounts are not loaded"));
+  const task = owner.queue.then(async () => {
+    assertCurrent(owner);
+    const { refs, anchor } = change(owner);
+    await save(owner, refs, anchor);
+    assertCurrent(owner);
+    publish(refs, anchor);
+  });
+  owner.queue = task.catch(() => {
+  });
+  return task;
+}
+function mount(ref) {
+  return mutate((owner) => ({ refs: withHome([...getMounts(), canonical(owner, ref)]), anchor: getAnchorRef() }));
+}
+function unmount(id) {
+  return mutate(() => {
+    if (id === getHomeAnchor().id) throw new Error("The home account cannot be unmounted");
+    const refs = withHome(getMounts().filter((ref) => ref.id !== id));
+    const anchor = refs.find((ref) => ref.id === getAnchorRef()?.id) ?? refs.find((ref) => ref.kind === "space") ?? getHomeAnchor();
+    return { refs, anchor };
+  });
+}
+function selectMount(ref) {
+  return mutate((owner) => {
+    const anchor = canonical(owner, ref);
+    return { refs: withHome([...getMounts(), anchor]), anchor };
+  });
+}
+function replaceMounts(refs, anchor) {
+  return mutate((owner) => {
+    const next = withHome(refs.map((ref) => canonical(owner, ref)));
+    const selected = canonical(owner, anchor);
+    if (!next.some((ref) => ref.id === selected.id)) throw new Error("Selected mount must be in the working set");
+    return { refs: next, anchor: selected };
+  });
+}
+
 // src/hooks.ts
 function useScopeKey() {
   return React.useSyncExternalStore(subscribeScope, getScopeVersion, getScopeVersion);
@@ -2528,44 +2673,13 @@ function useScope() {
   return { data, loading, error };
 }
 var EMPTY_ACCOUNTS = [];
-function membershipToMountRef(m) {
-  return {
-    id: m.accountId,
-    path: m.path,
-    kind: m.isSpace ? "space" : "account",
-    name: m.name,
-    grantedUnderAccountId: m.grantedUnderAccountId ?? void 0
-  };
-}
 function useAccounts() {
   const { user } = useAuth();
-  const autoSelectedRef = React.useRef(false);
+  const autoSelectedRef = React.useRef(null);
+  const [mountError, setMountError] = React.useState(null);
   const query = reactQuery.useQuery({
     queryKey: vfsKeys.memberships(user?.id ?? "anonymous"),
-    queryFn: async () => {
-      const result = await gatewayCall("list-memberships", {});
-      const memberships = result.memberships || [];
-      return memberships.map((m) => ({
-        accountId: m.account_id,
-        path: m.account_path,
-        name: m.account_name,
-        role: m.role || "member",
-        typeData: m.account_type_data || {},
-        joinedAt: m.joined_at,
-        via: m.via,
-        placement: m.placement,
-        subordinateTo: m.subordinate_to ?? null,
-        cascadeAnchorId: m.cascade_anchor_id ?? null,
-        isAccount: m.is_account ?? void 0,
-        isSpace: m.is_space ?? void 0,
-        isOwner: m.is_owner ?? void 0,
-        billingResponsible: m.billing_responsible ?? void 0,
-        grantedVia: m.granted_via ?? null,
-        grantedUnderAccountId: m.granted_under_account_id ?? null,
-        personalSpaceId: m.personal_space_id ?? null,
-        personalSpacePath: m.personal_space_path ?? null
-      }));
-    },
+    queryFn: fetchMemberships,
     enabled: !!user?.id,
     staleTime: 1e3 * 60 * 2
   });
@@ -2587,50 +2701,47 @@ function useAccounts() {
   }, [anchorVersion2, allMemberships]);
   React.useEffect(() => {
     if (!user?.id) {
-      autoSelectedRef.current = false;
+      autoSelectedRef.current = null;
       return;
     }
-    if (autoSelectedRef.current) return;
+    if (autoSelectedRef.current === user.id) return;
+    setMountError(null);
     if (electionCandidates.length === 1) {
       const only = electionCandidates[0];
-      electHomeAnchor(membershipToMountRef(only));
+      if (!getHomeAnchor()) electHomeAnchor(membershipToMountRef(only));
       initVfsRealtimeWs(only.accountId);
       if (only.personalSpacePath) {
         loadMounts(only.personalSpacePath, (id) => {
           const m = allMemberships.find((x) => x.accountId === id);
           return m ? membershipToMountRef(m) : null;
-        }).catch(() => {
-        });
+        }).catch(setMountError);
       }
-      autoSelectedRef.current = true;
+      autoSelectedRef.current = user.id;
     } else if (electionCandidates.length > 1) {
-      autoSelectedRef.current = true;
+      autoSelectedRef.current = user.id;
     }
   }, [user?.id, electionCandidates, allMemberships]);
-  const switchAccount = React.useCallback((accountPath) => {
+  const switchAccount = React.useCallback(async (accountPath) => {
     const m = allMemberships.find((a) => a.path === accountPath);
-    if (!m) return;
+    if (!m) throw new Error("Account membership is unavailable");
     const ref = membershipToMountRef(m);
     if (!getHomeAnchor()) {
       electHomeAnchor(ref);
-      if (m.personalSpacePath) {
-        loadMounts(m.personalSpacePath, (id) => {
-          const mm = allMemberships.find((x) => x.accountId === id);
-          return mm ? membershipToMountRef(mm) : null;
-        }).catch(() => {
-        });
-      }
-    } else {
-      setAnchor(ref);
     }
+    const home = allMemberships.find((a) => a.accountId === getHomeAnchor()?.id);
+    if (!home?.personalSpacePath) throw new Error("The home membership has no mount declaration location");
+    await loadMounts(home.personalSpacePath, (id) => {
+      const member = allMemberships.find((a) => a.accountId === id);
+      return member ? membershipToMountRef(member) : null;
+    });
+    await selectMount(ref);
+    setMountError(null);
     initVfsRealtimeWs(m.accountId);
   }, [allMemberships]);
-  const mountScope = React.useCallback((scopePath) => {
+  const mountScope = React.useCallback(async (scopePath) => {
     const m = allMemberships.find((a) => a.path === scopePath);
-    if (!m) return;
-    mount(membershipToMountRef(m)).catch(() => {
-    });
-    mountRealtimeScope(scopePath);
+    if (!m) throw new Error("Scope membership is unavailable");
+    await mount(membershipToMountRef(m));
   }, [allMemberships]);
   return {
     accounts: electionCandidates,
@@ -2640,17 +2751,19 @@ function useAccounts() {
     switchAccount,
     mountScope,
     loading: query.isLoading,
-    error: query.error
+    error: query.error ?? mountError
   };
 }
 function useMounts() {
+  useScopeKey();
   const version = React.useSyncExternalStore(subscribeMounts, getMountVersion, getMountVersion);
   const mounts = React.useMemo(() => getMounts(), [version]);
   return {
     mounts,
     homeAnchor: getHomeAnchor(),
     anchor: getAnchorRef(),
-    setAnchor,
+    setAnchor: selectMount,
+    replaceMounts,
     mount,
     unmount
   };
@@ -3397,6 +3510,7 @@ function normalizeChannel(raw) {
     isPrivate: td.is_private || false,
     isDm: td.is_dm || false,
     messageCount: td.message_count || 0,
+    createdAt: raw.created_at || "",
     updatedAt: raw.updated_at || "",
     chatScopePath: lineage.context_path || "",
     contextId: raw.scope_item_id || "",
@@ -4003,6 +4117,15 @@ function usePersonalItemOrder(key, items) {
   const scopePath = getScope();
   const supported = anchor?.kind === "space";
   const query = useArrangement(supported && scopePath ? { key, scope_id: anchor.id } : null);
+  const orderedItems = React.useMemo(() => {
+    const arranged = query.applyTo([...items]);
+    if (key !== "channel-order") return arranged;
+    const savedIds = new Set(query.order ?? []);
+    const unplaced = arranged.filter((item) => !savedIds.has(item.id));
+    const created = (item) => Date.parse(item.createdAt ?? "") || 0;
+    unplaced.sort((a, b) => created(b) - created(a));
+    return [...unplaced, ...arranged.filter((item) => savedIds.has(item.id))];
+  }, [key, items, query.applyTo, query.order]);
   const client2 = reactQuery.useQueryClient();
   const pending3 = React.useRef(false);
   const ready = Boolean(supported && !query.error && query.arrangement?.item_id && query.resolutionLevel === "member" && query.arrangement.write_target_id === query.arrangement.item_id);
@@ -4029,7 +4152,7 @@ function usePersonalItemOrder(key, items) {
     if (cached?.item_id !== query.arrangement.item_id || JSON.stringify(cached?.type_data?.order ?? []) !== JSON.stringify(query.order ?? [])) {
       throw new Error("The saved order changed. Try dragging again");
     }
-    const current = query.applyTo([...items]).map((item) => item.id);
+    const current = orderedItems.map((item) => item.id);
     if (ids.every((id, index2) => current[index2] === id)) return;
     const visible = new Set(visibleIds);
     let index = 0;
@@ -4048,7 +4171,7 @@ function usePersonalItemOrder(key, items) {
     }
   }
   return {
-    items: query.applyTo([...items]),
+    items: orderedItems,
     ready,
     supported,
     contextKey: `${generation}:${scopePath}:${key}`,
@@ -4336,34 +4459,109 @@ function startTracking(options = {}) {
   return trackingCleanup;
 }
 
-// src/initialize.ts
+// src/workspace.ts
 var initialization;
+registerCleanup(() => {
+  initialization = void 0;
+});
+function initializeWorkspace(options) {
+  if (initialization) {
+    if (initialization.accountPath !== options.accountPath) return Promise.reject(new Error("Reset the session before changing accounts"));
+    return initialization.promise;
+  }
+  const generation = getSessionGeneration();
+  const check = () => {
+    if (generation !== getSessionGeneration()) throw new Error("Workspace session changed");
+  };
+  const promise = (async () => {
+    const entry = await initSession();
+    check();
+    if (!entry.principal_id) throw new Error("Workspace initialization requires an authenticated principal");
+    const memberships = await getQueryClient().fetchQuery({
+      queryKey: vfsKeys.memberships(entry.principal_id),
+      queryFn: fetchMemberships,
+      staleTime: 12e4,
+      retry: false
+    });
+    check();
+    const account = memberships.find((m) => m.path === options.accountPath && m.isAccount && !m.isSpace);
+    if (!account) throw new Error("Authenticated account membership is unavailable");
+    const personal = memberships.find((m) => m.isSpace && m.accountId === account.personalSpaceId && m.path === account.personalSpacePath);
+    if (!personal || !account.personalSpacePath) throw new Error("A provisioned default Space membership is required");
+    const home = membershipToMountRef(account);
+    const defaultSpace = membershipToMountRef(personal);
+    const elected = getHomeAnchor();
+    if (elected && elected.id !== home.id) throw new Error("Reset the session before changing accounts");
+    if (!elected) electHomeAnchor(home, { activate: false });
+    await loadMounts(account.personalSpacePath, (id) => {
+      const member = memberships.find((m) => m.accountId === id && (m.isAccount || m.isSpace));
+      return member ? membershipToMountRef(member) : null;
+    }, { initialAnchor: defaultSpace });
+    check();
+    return { home, defaultSpace, memberships };
+  })().catch((error) => {
+    if (generation === getSessionGeneration()) initialization = void 0;
+    throw error;
+  });
+  initialization = { accountPath: options.accountPath, promise };
+  return promise;
+}
+
+// src/initialize.ts
+var initialization2;
+var stopActiveTracking;
+var workspaceAccount;
+registerCleanup(() => {
+  stopActiveTracking?.();
+  stopActiveTracking = void 0;
+  initialization2 = void 0;
+  workspaceAccount = void 0;
+});
 function initializeFsaos(options = {}) {
-  if (initialization) return initialization;
-  initialization = (async () => {
+  if (initialization2) {
+    if (options.workspace && options.workspace.accountPath !== workspaceAccount) {
+      return Promise.reject(new Error("Initialize workspace through initializeWorkspace, or dispose the existing runtime first"));
+    }
+    return initialization2;
+  }
+  workspaceAccount = options.workspace?.accountPath;
+  const generation = getSessionGeneration();
+  initialization2 = (async () => {
     const tracking = options.tracking ?? true;
     const stopTracking = tracking === false ? () => {
     } : startTracking(typeof tracking === "object" ? tracking : {});
+    stopActiveTracking = stopTracking;
     try {
       const session = options.session === false ? null : await initSession();
+      const workspace = options.workspace ? await initializeWorkspace(options.workspace) : void 0;
+      if (generation !== getSessionGeneration()) throw new Error("Session changed during initialization");
       let disposed = false;
       const runtime = {
         session,
+        workspace,
         dispose() {
           if (disposed) return;
           disposed = true;
           stopTracking();
-          initialization = void 0;
+          if (generation === getSessionGeneration()) {
+            initialization2 = void 0;
+            workspaceAccount = void 0;
+            stopActiveTracking = void 0;
+          }
         }
       };
       return runtime;
     } catch (error) {
       stopTracking();
-      initialization = void 0;
+      if (generation === getSessionGeneration()) {
+        initialization2 = void 0;
+        workspaceAccount = void 0;
+        stopActiveTracking = void 0;
+      }
       throw error;
     }
   })();
-  return initialization;
+  return initialization2;
 }
 
 // src/execution-control.ts
@@ -5458,6 +5656,7 @@ exports.hasServerClock = hasServerClock;
 exports.initSession = initSession;
 exports.initVfsRealtimeWs = initVfsRealtimeWs;
 exports.initializeFsaos = initializeFsaos;
+exports.initializeWorkspace = initializeWorkspace;
 exports.interpretSchema = interpretSchema;
 exports.invalidateAllVfs = invalidateAllVfs;
 exports.invalidateChannelMessages = invalidateChannelMessages;
@@ -5473,6 +5672,7 @@ exports.isListableItemsFilter = isListableItemsFilter;
 exports.isScopeReady = isScopeReady;
 exports.itemsFilterFromQueryFilter = itemsFilterFromQueryFilter;
 exports.listChildren = listChildren;
+exports.loadMounts = loadMounts;
 exports.mount = mount2;
 exports.mountRealtimeScope = mountRealtimeScope;
 exports.normalizeItem = normalizeItem;
@@ -5484,9 +5684,11 @@ exports.queryClient = queryClient;
 exports.readItem = readItem;
 exports.refreshQuery = refreshQuery;
 exports.registerCleanup = registerCleanup;
+exports.replaceMounts = replaceMounts;
 exports.resetAllSdkState = resetAllSdkState;
 exports.resolvePrincipalId = resolvePrincipalId;
 exports.resubscribePath = resubscribePath;
+exports.selectMount = selectMount;
 exports.serverDeadlinePassed = serverDeadlinePassed;
 exports.serverMsUntil = serverMsUntil;
 exports.serverNow = serverNow;