@ai4b-team/fsaos-gateway-sdk 3.33.0 → 3.34.1

package/README.md

@@ -200,6 +200,7 @@ reconciles the remaining count. No background polling is used.
 | `useChannelMessages(opts)` | Channel messages + bundled cards |
 | `useInfiniteChannelMessages(opts)` | Cursor-paginated messages (live tail) |
 | `useAllChannels()` / `useChannels()` / `useDmChannels()` | Channel lists (all / public / DM) |
+| `usePersonalItemOrder('channel-order' \| 'project-order', items)` | Apply and save the selected Space member's personal order through existing arrangements. |
 | `useNotifications(opts?)` | Notifications feed |
 | `useUnreadCounts(opts?)` | Aggregated unread counts |
 
@@ -295,3 +296,26 @@ This SDK has **zero** references to "kernel" in source, bundle, or type declarat
 and use this package as a dependency in your own applications, but you may **not**
 copy, modify, or redistribute it as a standalone library. All rights reserved by
 AI4B Team.
+
+### Personal channel and project ordering
+
+`usePersonalItemOrder(key, items)` reuses `resolve-arrangement` and the ordinary
+`update` primitive. Supply a complete collection of canonical IDs; render the
+returned `items` and call `reorder(ids)` once at drop. It returns `contextKey`
+for resetting in-progress UI gestures when the Space changes, plus `ready`,
+`supported`, `isLoading`, `isSaving`, `error`, `saveError` and `refetch`.
+
+The hook reads only the selected Space member's provisioned `channel-order` or
+`project-order` arrangement. Account mounts are unsupported and make no requests.
+It never creates a missing arrangement or falls back to a shared blueprint.
+Channels without a saved position appear **before** manually ordered channels,
+newest creation first using `Channel.createdAt` from the existing query payload.
+Missing/equal creation times retain source order. With no saved order, this is
+also the channel list's default order. Existing manually placed channels keep
+their relative positions. Arrival/removal performs no arrangement write; the
+next explicit reorder saves the supplied order. Project ordering is unchanged.
+A save preserves unseen IDs, rejects stale Space callbacks and invalid lists,
+and reconciles through the existing coalesced arrangement refresh. No polling,
+item reads or parent changes are involved. For paged collections, apply ordering
+in the backend before pagination; this hook does not discover Project folders
+or provide that paged read contract.