@datalayer/core 1.1.66 → 1.2.12

package/lib/hooks/useCache.js

@@ -38,13 +38,14 @@
  */
 import { useQuery, useQueries, useMutation, useQueryClient, } from '@tanstack/react-query';
 import { BOOTSTRAP_USER_ONBOARDING, asContact, asInvite, asOrganization, asSecret, asTeam, asToken, asUser, } from '../models/index.js';
-import { asPage, asSpace } from './cacheConverters.js';
+import { asSpace } from './cacheConverters.js';
 import { useCoreStore, useIAMStore, profileStore } from '../state/index.js';
 import { asDisplayName, namesAsInitials, asArray } from '../utils/index.js';
 import { useDatalayer } from './useDatalayer.js';
 import { useAuthorization } from './useAuthorization.js';
 import { useUploadForm } from './useUpload.js';
 import { OUTPUTSHOT_PLACEHOLDER_DEFAULT_SVG } from './assets/index.js';
+import { forgetSessionState } from '../state/sessionEnd.js';
 // Kept for potential future use
 // Default query options for all queries
 const DEFAULT_QUERY_OPTIONS = {
@@ -57,6 +58,53 @@ const DEFAULT_QUERY_OPTIONS = {
     // Ensure queries prioritize cache over network when data is fresh
     networkMode: 'online',
 };
+/**
+ * Refresh what a visitor sees, not just what the editor is looking at.
+ *
+ * `invalidateQueries` marks queries stale and refetches the **active** ones —
+ * the ones some mounted component is watching. Everything else is left to
+ * refetch when it is next mounted, which is the usual and correct behaviour
+ * and does not work here.
+ *
+ * It does not work because the app's `QueryClient` is built with
+ * `refetchOnMount: false`. A query that mounts holding stale data renders it
+ * and asks for nothing. So an administrator on `/admin/library/featured`
+ * would reorder the ribbon, watch the admin list reorder itself correctly —
+ * that query is active — and then find the home page still showing the old
+ * order, because the ribbon was not mounted when the invalidation happened
+ * and would not ask again when it was. Only a full page reload, which throws
+ * the whole cache away, put it right.
+ *
+ * `refetchType: 'all'` fetches the inactive ones too, there and then. It
+ * belongs on the handful of mutations that change what somebody *else's*
+ * screen shows, and nowhere else: for an ordinary edit, refetching every
+ * dormant query in the cache is a burst of requests for pages nobody is on.
+ */
+const invalidateEverywhere = (client, queryKey) => {
+    void client.invalidateQueries({ queryKey, refetchType: 'all' });
+};
+/**
+ * Forget everything a session was told, without orphaning what is on screen.
+ *
+ * `queryClient.clear()` is the obvious way to end a session and the wrong
+ * one. It destroys the query objects themselves, and an observer whose query
+ * is destroyed while its fetch is in flight is never answered and never asks
+ * again: it sits at `isLoading` for as long as the page stays open.
+ *
+ * Signing out is exactly that race. Ending the session swaps the whole tree
+ * for the anonymous one, which mounts the home page and starts fetching the
+ * featured ribbon; the logout response then lands on top of that fetch. The
+ * ribbon stayed a row of empty placeholders until the reader reloaded.
+ *
+ * So: drop what nobody is looking at, and reset what is on screen. A reset
+ * forgets the answer the person who has left was given and asks the question
+ * again as whoever is here now, which is what signing out means for a page
+ * that is still open.
+ */
+export const forgetSession = (client) => {
+    client.removeQueries({ type: 'inactive' });
+    client.resetQueries({ type: 'active' });
+};
 // ============================================================================
 // Query Key Factories
 // ============================================================================
@@ -132,14 +180,26 @@ export const queryKeys = {
         mcpCall: (sessionUid, callUid) => [...queryKeys.contents.mcpCalls(sessionUid), callUid],
         mcpApprovals: () => [...queryKeys.contents.all(), 'mcp-approvals'],
         mcpApprovalList: (filters) => [...queryKeys.contents.mcpApprovals(), 'list', filters ?? {}],
-        datasourceSchema: (sourceUid) => [...queryKeys.contents.source(sourceUid), 'datasource', 'schema'],
-        datasourceCapabilities: (sourceUid) => [...queryKeys.contents.source(sourceUid), 'datasource', 'capabilities'],
+        datasourceSchema: (sourceUid) => [
+            ...queryKeys.contents.source(sourceUid),
+            'datasource',
+            'schema',
+        ],
+        datasourceCapabilities: (sourceUid) => [
+            ...queryKeys.contents.source(sourceUid),
+            'datasource',
+            'capabilities',
+        ],
         datasourceQueries: (sourceUid) => [...queryKeys.contents.source(sourceUid), 'queries'],
         // A query is addressed by its own uid, not under its source: a
         // notebook reconnects to one by uid alone.
         queries: () => [...queryKeys.contents.all(), 'queries'],
         query: (queryUid) => [...queryKeys.contents.queries(), queryUid],
-        dataserverStatus: (sourceUid) => [...queryKeys.contents.source(sourceUid), 'dataserver', 'status'],
+        dataserverStatus: (sourceUid) => [
+            ...queryKeys.contents.source(sourceUid),
+            'dataserver',
+            'status',
+        ],
     },
     // The Jupyter MCP Server: what the agents did, and what they may do
     mcp: {
@@ -147,7 +207,12 @@ export const queryKeys = {
         tasks: () => [...queryKeys.mcp.all(), 'tasks'],
         taskList: (filters) => [...queryKeys.mcp.tasks(), 'list', filters ?? {}],
         task: (taskUid) => [...queryKeys.mcp.tasks(), taskUid],
-        notebookTasks: (notebookUid, filters) => [...queryKeys.mcp.tasks(), 'notebook', notebookUid, filters ?? {}],
+        notebookTasks: (notebookUid, filters) => [
+            ...queryKeys.mcp.tasks(),
+            'notebook',
+            notebookUid,
+            filters ?? {},
+        ],
         bindings: () => [...queryKeys.mcp.all(), 'bindings'],
         bindingList: (filters) => [...queryKeys.mcp.bindings(), 'list', filters ?? {}],
         activity: (filters) => [...queryKeys.mcp.all(), 'activity', filters ?? {}],
@@ -163,6 +228,12 @@ export const queryKeys = {
         // shared entry would show one under the other's name.
         policyLayer: (scope, subjectUid) => [...queryKeys.mcp.all(), 'policy-layer', scope, subjectUid],
         alertRules: (orgUid) => [...queryKeys.mcp.all(), 'alert-rules', orgUid],
+        identityProviders: (orgUid) => [...queryKeys.mcp.all(), 'identity-providers', orgUid],
+        scimTokens: (orgUid) => [...queryKeys.mcp.all(), 'scim-tokens', orgUid],
+        // Keyed by scope *and* subject, like `policyLayer`: an organization's
+        // admitted clients and a team's are different lists, and a shared entry
+        // would show one under the other's name.
+        admittedClients: (scope, subjectUid) => [...queryKeys.mcp.all(), 'admitted-clients', scope, subjectUid],
         forwarding: (orgUid) => [...queryKeys.mcp.all(), 'audit-forwarding', orgUid],
         auditSettings: (orgUid) => [...queryKeys.mcp.all(), 'audit-settings', orgUid],
         organizationTeams: (orgUid) => [...queryKeys.mcp.all(), 'organization-teams', orgUid],
@@ -177,8 +248,20 @@ export const queryKeys = {
         workflows: () => [...queryKeys.mcp.operations(), 'workflows'],
         gatewayVersion: () => [...queryKeys.mcp.all(), 'version'],
         // The Enterprise console: one answer per organization, narrowed by team.
-        orgOverview: (orgUid, filters) => [...queryKeys.mcp.all(), 'organizations', orgUid, 'overview', filters ?? {}],
-        orgUsage: (orgUid, filters) => [...queryKeys.mcp.all(), 'organizations', orgUid, 'usage', filters ?? {}],
+        orgOverview: (orgUid, filters) => [
+            ...queryKeys.mcp.all(),
+            'organizations',
+            orgUid,
+            'overview',
+            filters ?? {},
+        ],
+        orgUsage: (orgUid, filters) => [
+            ...queryKeys.mcp.all(),
+            'organizations',
+            orgUid,
+            'usage',
+            filters ?? {},
+        ],
     },
     // Authentication & Profile
     auth: {
@@ -262,6 +345,14 @@ export const queryKeys = {
         bySpace: (spaceId) => [...queryKeys.documents.all(), 'space', spaceId],
         model: (documentId) => [...queryKeys.documents.detail(documentId), 'model'],
     },
+    // Decks
+    decks: {
+        all: () => ['decks'],
+        details: () => [...queryKeys.decks.all(), 'detail'],
+        detail: (id) => [...queryKeys.decks.details(), id],
+        bySpace: (spaceId) => [...queryKeys.decks.all(), 'space', spaceId],
+        model: (deckId) => [...queryKeys.decks.detail(deckId), 'model'],
+    },
     // Cells
     cells: {
         all: () => ['cells'],
@@ -308,12 +399,6 @@ export const queryKeys = {
         detail: (id) => [...queryKeys.environments.details(), id],
         bySpace: (spaceId) => [...queryKeys.environments.all(), 'space', spaceId],
     },
-    // Pages
-    pages: {
-        all: () => ['pages'],
-        details: () => [...queryKeys.pages.all(), 'detail'],
-        detail: (id) => [...queryKeys.pages.details(), id],
-    },
     // Secrets
     secrets: {
         all: () => ['secrets'],
@@ -371,8 +456,16 @@ export const queryKeys = {
     items: {
         all: () => ['items'],
         public: () => [...queryKeys.items.all(), 'public'],
+        publicItem: (uid) => [...queryKeys.items.all(), 'public', uid],
         bySpace: (spaceId) => [...queryKeys.items.all(), 'space', spaceId],
         search: (opts) => [...queryKeys.items.all(), 'search', opts],
+        // The library: what the home page, the profile pages and "my orbits"
+        // read, each invalidated by the mutation that changes it.
+        featured: () => [...queryKeys.items.all(), 'featured'],
+        orbits: () => [...queryKeys.items.all(), 'orbits'],
+        orbiters: (uid) => [...queryKeys.items.all(), 'orbiters', uid],
+        derivations: (uid) => [...queryKeys.items.all(), 'derivations', uid],
+        byOwner: (handle) => [...queryKeys.items.all(), 'owner', handle],
     },
     // Layout
     layout: {
@@ -453,6 +546,8 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
     const { isLoading: notebookUploadLoading, uploadAndSubmit: uploadNotebook, progress: notebookUploadProgress, reset: resetNotebookUpload, } = useUploadForm(`${coreStore.configuration.spacerUrl}/api/spacer/v1/notebooks`);
     // Hook for document upload/creation
     const { isLoading: documentUploadLoading, uploadAndSubmit: uploadDocument, progress: documentUploadProgress, reset: resetDocumentUpload, } = useUploadForm(`${coreStore.configuration.spacerUrl}/api/spacer/v1/lexicals`);
+    // Hook for deck upload/creation
+    const { isLoading: deckUploadLoading, uploadAndSubmit: uploadDeck, progress: deckUploadProgress, reset: resetDeckUpload, } = useUploadForm(`${coreStore.configuration.spacerUrl}/api/spacer/v1/decks`);
     // ============================================================================
     // Transformation Functions (kept from original useCache)
     // Note: These functions use 'any' because they handle dynamic API responses
@@ -552,11 +647,6 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
     const toSpace = (spc) => {
         return asSpace(spc);
     };
-    const toPage = (s) => {
-        if (s) {
-            return asPage(s);
-        }
-    };
     const toSecret = (s) => {
         if (s) {
             return asSecret(s);
@@ -582,6 +672,232 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
      * is available so the UI hydration hooks (e.g. `useUsersByUids`) can
      * still fill in display data downstream.
      */
+    /**
+     * What the library knows about an artifact, on top of what its own service
+     * stores: how many people orbit it, whether this visitor does, how often it
+     * has been reused, whether it is featured, and what it looks like.
+     *
+     * Applied in one place — `toItem`, the library and search path — rather than
+     * in each mapper: a notebook read from its space has none of this, and
+     * inventing zeros there would say "nobody orbits it" where the truth is
+     * "this was not the library answering".
+     */
+    const withLibraryMeta = (raw) => {
+        if (!raw || typeof raw !== 'object') {
+            return {};
+        }
+        const meta = {};
+        if (raw.orbits !== undefined)
+            meta.orbits = Number(raw.orbits) || 0;
+        if (raw.orbited !== undefined)
+            meta.orbited = Boolean(raw.orbited);
+        if (raw.clones !== undefined)
+            meta.clones = Number(raw.clones) || 0;
+        if (raw.instantiations !== undefined)
+            meta.instantiations = Number(raw.instantiations) || 0;
+        if (raw.featured !== undefined)
+            meta.featured = Boolean(raw.featured);
+        if (raw.featuredRank !== undefined)
+            meta.featuredRank = Number(raw.featuredRank);
+        if (raw.reuse !== undefined)
+            meta.reuse = raw.reuse;
+        if (raw.publisher !== undefined)
+            meta.publisher = raw.publisher;
+        if (raw.image !== undefined)
+            meta.image = raw.image;
+        /*
+         * Where the artifact can be opened for editing.
+         *
+         * An item is a nested child of its space and carries no handle of its
+         * own, so the library resolves the space when it projects one. Without
+         * these two a page can link to the public reading of an artifact and has
+         * no way to offer the editable one.
+         */
+        if (raw.space_handle_s)
+            meta.spaceHandle = raw.space_handle_s;
+        if (raw.space_owner_handle_s)
+            meta.spaceOwnerHandle = raw.space_owner_handle_s;
+        /*
+         * The absolute address anyone can read it at.
+         *
+         * Built by the library, not here, because it needs the host the site is
+         * served from and the browser only knows the host it happens to be on —
+         * which on a development server is `localhost:3063`, the one address that
+         * is no use to whoever the link is being copied for.
+         */
+        if (raw.publicUrl)
+            meta.publicUrl = raw.publicUrl;
+        if (raw.shareCardUrl)
+            meta.shareCardUrl = raw.shareCardUrl;
+        if (raw.shareCardVersion)
+            meta.shareCardVersion = raw.shareCardVersion;
+        return meta;
+    };
+    /**
+     * A published dataset. Keyed on the dataset it is a publication of, not on
+     * the publication: republishing mints a new immutable revision, and the
+     * library entry — with the orbits it has collected — is the dataset's.
+     */
+    const toDataset = (raw) => {
+        const owner = toItemOwner(raw);
+        return {
+            id: raw.uid,
+            type: 'dataset',
+            name: raw.name_t,
+            description: raw.description_t,
+            tags: Array.isArray(raw.tags_ss) ? raw.tags_ss : [],
+            public: raw.is_public_b ?? true,
+            license: raw.license_s,
+            fileCount: raw.file_count_i,
+            totalSize: raw.total_size_l,
+            publicationId: raw.latest_publication_uid_s,
+            revisionId: raw.revision_uid_s,
+            creationDate: raw.creation_ts_dt
+                ? new Date(raw.creation_ts_dt)
+                : undefined,
+            owner,
+        };
+    };
+    /**
+     * An agent as a library artifact: published by Datalayer rather than by a
+     * user, and reused by instantiating a runtime from its specification rather
+     * than by cloning a document. The specification itself lives in the
+     * application's own build; this is only what the library shows of it.
+     */
+    /**
+     * A published Data Server: its catalog, never its address.
+     *
+     * What the library holds is what it answers for — the connector kinds and
+     * the relations they name. Reusing one attaches it as a Datasource; there
+     * is nothing to copy, because a Data Server is a process somebody runs.
+     */
+    const toDataserver = (raw) => {
+        const owner = toItemOwner(raw);
+        return {
+            id: raw.uid,
+            type: 'dataserver',
+            name: raw.name_t,
+            description: raw.description_t,
+            tags: Array.isArray(raw.tags_ss) ? raw.tags_ss : [],
+            public: raw.is_public_b ?? true,
+            connectors: Array.isArray(raw.connectors_ss) ? raw.connectors_ss : [],
+            relations: Array.isArray(raw.relations_ss) ? raw.relations_ss : [],
+            publicationId: raw.latest_publication_uid_s,
+            creationDate: raw.creation_ts_dt
+                ? new Date(raw.creation_ts_dt)
+                : undefined,
+            owner,
+        };
+    };
+    const toAgent = (raw) => {
+        return {
+            id: raw.uid,
+            type: 'agent',
+            name: raw.name_t,
+            description: raw.description_t,
+            tags: Array.isArray(raw.tags_ss) ? raw.tags_ss : [],
+            public: raw.is_public_b ?? true,
+            domain: raw.domain_s,
+            icon: raw.icon_s,
+            emoji: raw.emoji_s,
+            model: raw.model_s,
+            specId: String(raw.uid || '').replace(/^agent:/, ''),
+            specVersion: raw.spec_version_s,
+            publisher: raw.publisher_s || 'datalayer',
+            creationDate: raw.creation_ts_dt
+                ? new Date(raw.creation_ts_dt)
+                : undefined,
+        };
+    };
+    /**
+     * A published benchmark report (B5-01): what it is about and where it
+     * stands, and the document it is written in, which the library reads for it
+     * and hands over as `model_s` — the field a document's reader looks for.
+     */
+    const toReport = (raw) => {
+        return {
+            id: raw.uid,
+            type: 'report',
+            name: raw.name_t,
+            description: raw.description_t,
+            tags: Array.isArray(raw.tags_ss) ? raw.tags_ss : [],
+            public: raw.is_public_b ?? true,
+            state: raw.state_s,
+            version: raw.version_i,
+            runCount: raw.run_count_i,
+            evalsetId: raw.evalset_uid_s,
+            report: raw.report,
+            model_s: raw.model_s,
+            creationDate: raw.creation_ts_dt
+                ? new Date(raw.creation_ts_dt)
+                : undefined,
+            lastPublicationDate: raw.published_ts_dt
+                ? new Date(raw.published_ts_dt)
+                : undefined,
+            owner: toItemOwner(raw),
+        };
+    };
+    /**
+     * A published investigation (B5-01): its scope, where it stands and what was
+     * decided, and the document it is written in, as a report's is.
+     */
+    const toInvestigation = (raw) => {
+        return {
+            id: raw.uid,
+            type: 'investigation',
+            name: raw.name_t,
+            description: raw.description_t,
+            tags: Array.isArray(raw.tags_ss) ? raw.tags_ss : [],
+            public: raw.is_public_b ?? true,
+            scope: raw.scope_s,
+            status: raw.status_s,
+            evalsetId: raw.evalset_uid_s,
+            investigation: raw.investigation,
+            model_s: raw.model_s,
+            creationDate: raw.creation_ts_dt
+                ? new Date(raw.creation_ts_dt)
+                : undefined,
+            lastPublicationDate: raw.published_ts_dt
+                ? new Date(raw.published_ts_dt)
+                : undefined,
+            owner: toItemOwner(raw),
+        };
+    };
+    /** An evaluator of the platform's catalogue (B5-01), published as an agent is. */
+    const toEvaluator = (raw) => {
+        return {
+            id: raw.uid,
+            type: 'evaluator',
+            name: raw.name_t,
+            description: raw.description_t,
+            tags: Array.isArray(raw.tags_ss) ? raw.tags_ss : [],
+            public: raw.is_public_b ?? true,
+            specId: String(raw.uid || '').replace(/^evaluator:/, ''),
+            specVersion: raw.spec_version_s,
+            publisher: raw.publisher_s || 'datalayer',
+            creationDate: raw.creation_ts_dt
+                ? new Date(raw.creation_ts_dt)
+                : undefined,
+        };
+    };
+    /**
+     * A card of the site's own in the featured ribbon — the run the home page is
+     * written about, say. The library knows its name and whether it is
+     * featured; what it draws and where it leads are in the application's build,
+     * keyed by `cardId`.
+     */
+    const toSiteCard = (raw) => {
+        return {
+            id: raw.uid,
+            type: 'sitecard',
+            name: raw.name_t,
+            description: raw.description_t,
+            tags: Array.isArray(raw.tags_ss) ? raw.tags_ss : [],
+            public: raw.is_public_b ?? true,
+            cardId: String(raw.uid || '').replace(/^sitecard:/, ''),
+            publisher: raw.publisher_s || 'datalayer',
+        };
+    };
     const toItemOwner = (raw) => {
         const uid = String(raw?.creator_uid_s ??
             raw?.creator_uid ??
@@ -593,6 +909,15 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
         const lastName = String(raw?.creator_last_name_t ?? raw?.last_name_t ?? '').trim();
         const email = String(raw?.creator_email_s ?? raw?.email_s ?? '').trim();
         const displayName = firstName || lastName ? asDisplayName(firstName, lastName) : handle;
+        /*
+         * The face, which the library has been projecting all along and nothing
+         * was reading. Without it every published artifact was attributed to a
+         * pair of initials, on its own public page as much as anywhere else —
+         * the owner is right there in the projection, and this is the one place
+         * it was being dropped.
+         */
+        const avatarUrl = String(raw?.creator_avatar_url_s ?? raw?.avatar_url_s ?? '').trim();
+        const avatarIcon = String(raw?.creator_avatar_icon_s ?? raw?.avatar_icon_s ?? '').trim();
         return {
             id: uid,
             handle,
@@ -601,6 +926,8 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             lastName,
             initials: namesAsInitials(firstName, lastName),
             displayName,
+            avatarUrl: avatarUrl || undefined,
+            avatarIcon: avatarIcon || undefined,
             roles: [],
             iamProviders: [],
             setRoles: () => { },
@@ -619,6 +946,17 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             type: 'cell',
             name: cl.name_t,
             description: cl.description_t,
+            /*
+             * The words its owner filed it under.
+             *
+             * Every artifact type the library holds carries `tags_ss`, and the six
+             * space items — notebook, document, cell, lesson, exercise, assignment
+             * — were the six that never read it. So a notebook could be published
+             * under tags, be found by them in a search, and arrive at the card that
+             * shows them with none: the field was dropped here, one layer below
+             * anything that could notice.
+             */
+            tags: Array.isArray(cl.tags_ss) ? cl.tags_ss : [],
             source: cl.source_t,
             creationDate: new Date(cl.creation_ts_dt),
             public: cl.is_public_b ?? false,
@@ -644,6 +982,7 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             type: 'notebook',
             name: raw_notebook.name_t,
             description: raw_notebook.description_t,
+            tags: Array.isArray(raw_notebook.tags_ss) ? raw_notebook.tags_ss : [],
             nbformat: raw_notebook.model_s
                 ? JSON.parse(raw_notebook.model_s)
                 : undefined,
@@ -666,6 +1005,49 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             },
         };
     };
+    /**
+     * Put a deck in the detail cache — but only a whole one.
+     *
+     * A listing answers with the space's items, and an item carries no
+     * `model_s`: the specification lives in S3 and only `GET /decks/{uid}`
+     * inlines it. Seeding the detail cache from such a row left `useDeck`
+     * answering instantly with a deck whose `spec` is undefined — and since
+     * these queries stay fresh for five minutes and do not refetch on mount,
+     * an editor opened from the table drew nothing until the tab was reloaded.
+     * A deck without its specification is not the deck this cache promises.
+     */
+    const seedDeckDetail = (deck) => {
+        if (deck?.spec) {
+            queryClient.setQueryData(queryKeys.decks.detail(deck.id), deck);
+        }
+    };
+    const toDeck = (raw) => {
+        const owner = toItemOwner(raw);
+        return {
+            id: raw.uid,
+            type: 'deck',
+            name: raw.name_t,
+            description: raw.description_t,
+            tags: Array.isArray(raw.tags_ss) ? raw.tags_ss : [],
+            spec: raw.model_s ? JSON.parse(raw.model_s) : undefined,
+            public: raw.is_public_b ?? false,
+            creationDate: new Date(raw.creation_ts_dt),
+            lastUpdateDate: raw.last_update_ts_dt
+                ? new Date(raw.last_update_ts_dt)
+                : undefined,
+            lastPublicationDate: raw.creation_ts_dt
+                ? new Date(raw.creation_ts_dt)
+                : undefined,
+            owner,
+            space: {
+                handle: raw.handle_s,
+            },
+            organization: {
+                id: raw.organization_uid_s,
+                handle: raw.organization_handle_s,
+            },
+        };
+    };
     const toDocument = (doc) => {
         const owner = toItemOwner(doc);
         return {
@@ -673,6 +1055,7 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             type: 'document',
             name: doc.name_t,
             description: doc.description_t,
+            tags: Array.isArray(doc.tags_ss) ? doc.tags_ss : [],
             model: doc.model_s ? JSON.parse(doc.model_s) : undefined,
             public: doc.is_public_b ?? false,
             creationDate: new Date(doc.creation_ts_dt),
@@ -699,6 +1082,7 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             type: 'lesson',
             name: raw_lesson.name_t,
             description: raw_lesson.description_t,
+            tags: Array.isArray(raw_lesson.tags_ss) ? raw_lesson.tags_ss : [],
             nbformat: raw_lesson.model_s ? JSON.parse(raw_lesson.model_s) : undefined,
             public: raw_lesson.is_public_b ?? false,
             creationDate: new Date(raw_lesson.creation_ts_dt),
@@ -726,6 +1110,7 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             type: 'exercise',
             name: ex.name_t,
             description: ex.description_t,
+            tags: Array.isArray(ex.tags_ss) ? ex.tags_ss : [],
             help: ex.help_t,
             codePre: ex.code_pre_t,
             codeQuestion: ex.code_question_t,
@@ -771,6 +1156,7 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             type: 'assignment',
             name: raw_assignment.name_t,
             description: raw_assignment.description_t,
+            tags: Array.isArray(raw_assignment.tags_ss) ? raw_assignment.tags_ss : [],
             nbformat: raw_assignment.model_s
                 ? JSON.parse(raw_assignment.model_s)
                 : undefined,
@@ -818,6 +1204,13 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
     };
     const toEvalset = (raw_evalset) => {
         const owner = toItemOwner(raw_evalset);
+        const numberOrUndefined = (value) => {
+            if (value === null || value === undefined || value === '') {
+                return undefined;
+            }
+            const parsed = Number(value);
+            return Number.isFinite(parsed) ? parsed : undefined;
+        };
         return {
             id: raw_evalset.uid,
             type: 'evalset',
@@ -831,6 +1224,70 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                 ? new Date(raw_evalset.last_update_ts_dt)
                 : undefined,
             tags: Array.isArray(raw_evalset.tags_ss) ? raw_evalset.tags_ss : [],
+            /*
+             * What the runs of a benchmark say about it, projected onto its
+             * library card whenever a run moves (BENCHMARK.md, B2-10 and B1-09).
+             *
+             * These were dropped here, so a card in the Library or on the home
+             * page could show a name and a description and nothing that would
+             * help anybody choose between two benchmarks — how big it is, what it
+             * has been run on, how well anyone has done, what a run tends to
+             * cost. The projection has been writing them all along.
+             */
+            category: raw_evalset.category_s || undefined,
+            caseCount: numberOrUndefined(raw_evalset.case_count_i),
+            runCount: numberOrUndefined(raw_evalset.run_count_i),
+            latestPassRate: numberOrUndefined(raw_evalset.latest_pass_rate_f),
+            bestPassRate: numberOrUndefined(raw_evalset.best_pass_rate_f),
+            lastRunStatus: raw_evalset.last_run_status_s || undefined,
+            lastRunAt: raw_evalset.last_run_at_dt
+                ? new Date(raw_evalset.last_run_at_dt)
+                : undefined,
+            estimatedCost: numberOrUndefined(raw_evalset.estimated_cost_f),
+            environment: raw_evalset.environment_s || undefined,
+            subjectRefs: Array.isArray(raw_evalset.subject_refs_ss)
+                ? raw_evalset.subject_refs_ss
+                : [],
+            owner,
+        };
+    };
+    /**
+     * A published environment version as a library artifact (PLAN_ENV E2-16).
+     *
+     * Keyed on the version uid, so one published version is one card, and read
+     * from the publication's immutable snapshot: its name, title, README (the
+     * description), the licenses its SBOM names (the tags), its size class and
+     * the variants it was built for. Republishing mints a new version — and a
+     * new card — rather than moving this one.
+     */
+    const toEnvironmentArtifact = (raw) => {
+        const owner = toItemOwner(raw);
+        const numberOrUndefined = (value) => {
+            if (value === null || value === undefined || value === '') {
+                return undefined;
+            }
+            const parsed = Number(value);
+            return Number.isFinite(parsed) ? parsed : undefined;
+        };
+        return {
+            id: raw.uid,
+            type: 'environment',
+            name: raw.name_t,
+            title: raw.title_t || undefined,
+            description: raw.description_t,
+            tags: Array.isArray(raw.tags_ss) ? raw.tags_ss : [],
+            licenses: Array.isArray(raw.tags_ss) ? raw.tags_ss : [],
+            public: raw.is_public_b ?? true,
+            environmentUid: raw.environment_uid_s || undefined,
+            sizeClass: raw.size_class_s || undefined,
+            variants: Array.isArray(raw.variants_ss) ? raw.variants_ss : [],
+            versionNumber: numberOrUndefined(raw.version_number_i),
+            creationDate: raw.creation_ts_dt
+                ? new Date(raw.creation_ts_dt)
+                : undefined,
+            lastUpdateDate: raw.source_update_ts_dt
+                ? new Date(raw.source_update_ts_dt)
+                : undefined,
             owner,
         };
     };
@@ -839,6 +1296,13 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             console.error('No type_s found on item', item);
             return {};
         }
+        // The library answers with the same field names a space item has, plus
+        // what only it knows; the type mapper reads the former and
+        // `withLibraryMeta` adds the latter, so one artifact has one shape
+        // wherever it was searched.
+        return { ...toTypedItem(item), ...withLibraryMeta(item) };
+    };
+    const toTypedItem = (item) => {
         switch (item.type_s) {
             case 'assignment':
                 return toAssignment(item);
@@ -883,6 +1347,10 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                     },
                 };
             }
+            // Without this the mapper answered `{}` for a deck: the card then
+            // read no type and no name, and drew itself as a nameless notebook.
+            case 'deck':
+                return toDeck(item);
             case 'document':
                 return toDocument(item);
             case 'exercise':
@@ -891,10 +1359,24 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                 return toLesson(item);
             case 'notebook':
                 return toNotebook(item);
-            case 'page':
-                return toPage(item);
             case 'evalset':
                 return toEvalset(item);
+            case 'environment':
+                return toEnvironmentArtifact(item);
+            case 'dataset':
+                return toDataset(item);
+            case 'agent':
+                return toAgent(item);
+            case 'dataserver':
+                return toDataserver(item);
+            case 'report':
+                return toReport(item);
+            case 'investigation':
+                return toInvestigation(item);
+            case 'evaluator':
+                return toEvaluator(item);
+            case 'sitecard':
+                return toSiteCard(item);
             default:
                 return {};
         }
@@ -1020,8 +1502,8 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                 });
             },
             onSuccess: () => {
-                // Clear all queries on logout
-                queryClient.clear();
+                forgetSession(queryClient);
+                forgetSessionState();
             },
         });
     };
@@ -1058,11 +1540,11 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
      */
     const useUpdateMe = () => {
         return useMutation({
-            mutationFn: async ({ email, firstName, lastName, avatarIcon, banner, }) => {
+            mutationFn: async ({ email, firstName, lastName, avatarIcon, banner, showOrbits, }) => {
                 return requestDatalayer({
                     url: `${configuration.iamUrl}/api/iam/v1/me`,
                     method: 'PUT',
-                    body: { email, firstName, lastName, avatarIcon, banner },
+                    body: { email, firstName, lastName, avatarIcon, banner, showOrbits },
                 });
             },
             onSuccess: () => {
@@ -1296,19 +1778,33 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
     const useUpdateUserSettings = () => {
         return useMutation({
             mutationFn: async ({ userId, settings, }) => {
+                // Only the keys the caller actually set. IAM merges what it
+                // receives into the settings document, so sending a key means
+                // changing it — an undefined one is dropped by `JSON.stringify`
+                // and leaves the stored value alone.
+                const body = {};
+                if (settings.aiAgentsUrl !== undefined) {
+                    body.aiAgents_url_s = settings.aiAgentsUrl;
+                }
+                if (settings.canInvite !== undefined) {
+                    body.can_invite_b = settings.canInvite;
+                }
+                if (settings.docsInPlace !== undefined) {
+                    body.docs_in_place_b = settings.docsInPlace;
+                }
                 return requestDatalayer({
                     url: `${configuration.iamUrl}/api/iam/v1/users/${userId}/settings`,
                     method: 'PUT',
-                    body: {
-                        aiAgents_url_s: settings.aiAgentsUrl,
-                        can_invite_b: settings.canInvite || false,
-                    },
+                    body,
                 });
             },
             onSuccess: (_, variables) => {
                 queryClient.invalidateQueries({
                     queryKey: queryKeys.users.detail(variables.userId),
                 });
+                // The signed-in user carries these settings, and the application
+                // shell reads them from there.
+                queryClient.invalidateQueries({ queryKey: queryKeys.auth.me() });
             },
         });
     };
@@ -1938,6 +2434,148 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             },
         });
     };
+    /**
+     * Get a deck by id, its specification inlined as `spec`.
+     */
+    const useDeck = (deckId) => {
+        return useQuery({
+            queryKey: queryKeys.decks.detail(deckId),
+            queryFn: async () => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.spacerUrl}/api/spacer/v1/decks/${deckId}`,
+                    method: 'GET',
+                });
+                if (resp.success && resp.deck) {
+                    return toDeck(resp.deck);
+                }
+                if (resp?.code === 'FORBIDDEN') {
+                    throw new Error(resp.message || 'Not authorized to access this deck');
+                }
+                throw new Error(resp.message || 'Failed to fetch deck');
+            },
+            ...DEFAULT_QUERY_OPTIONS,
+            enabled: !!deckId,
+        });
+    };
+    /**
+     * Get decks by space
+     */
+    const useDecksBySpace = (spaceId) => {
+        return useQuery({
+            queryKey: queryKeys.decks.bySpace(spaceId),
+            queryFn: async () => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.spacerUrl}/api/spacer/v1/spaces/${spaceId}/items/types/deck`,
+                    method: 'GET',
+                });
+                if (resp.success && resp.items) {
+                    return resp.items.map((raw) => {
+                        const deck = toDeck(raw);
+                        seedDeckDetail(deck);
+                        return deck;
+                    });
+                }
+                return [];
+            },
+            ...DEFAULT_QUERY_OPTIONS,
+            enabled: !!spaceId,
+        });
+    };
+    /**
+     * Create a deck — from an uploaded specification, or the starter one.
+     */
+    const useCreateDeck = () => {
+        return useMutation({
+            mutationFn: async ({ spaceId, name, description, deckType = 'deck', file, }) => {
+                const formData = new FormData();
+                formData.append('space_id', spaceId);
+                // Backward compatibility for endpoints still expecting camelCase.
+                formData.append('spaceId', spaceId);
+                formData.append('deckType', deckType);
+                formData.append('name', name);
+                formData.append('description', description || '');
+                if (file) {
+                    formData.append('file', file);
+                }
+                return uploadDeck(formData);
+            },
+            onSuccess: resp => {
+                if (resp.success && resp.deck) {
+                    const deck = toDeck(resp.deck);
+                    seedDeckDetail(deck);
+                    queryClient.refetchQueries({ queryKey: queryKeys.decks.all() });
+                    queryClient.refetchQueries({ queryKey: queryKeys.items.all() });
+                }
+            },
+        });
+    };
+    /**
+     * Update a deck's name and description
+     */
+    const useUpdateDeck = () => {
+        return useMutation({
+            mutationFn: async ({ id, name, description, }) => {
+                return requestDatalayer({
+                    url: `${configuration.spacerUrl}/api/spacer/v1/decks/${id}`,
+                    method: 'PUT',
+                    body: { name, description },
+                });
+            },
+            onSuccess: (resp, deck) => {
+                if (resp.success) {
+                    queryClient.invalidateQueries({
+                        queryKey: queryKeys.decks.detail(deck.id),
+                    });
+                    queryClient.invalidateQueries({ queryKey: queryKeys.decks.all() });
+                }
+            },
+        });
+    };
+    /**
+     * Replace a deck's specification, whole.
+     */
+    const useUpdateDeckModel = () => {
+        return useMutation({
+            mutationFn: async ({ deckId, spec, }) => {
+                return requestDatalayer({
+                    url: `${configuration.spacerUrl}/api/spacer/v1/decks/${deckId}/model`,
+                    method: 'PUT',
+                    body: { spec },
+                });
+            },
+            onSuccess: (_, variables) => {
+                queryClient.invalidateQueries({
+                    queryKey: queryKeys.decks.detail(variables.deckId),
+                });
+                queryClient.invalidateQueries({
+                    queryKey: queryKeys.decks.model(variables.deckId),
+                });
+                queryClient.invalidateQueries({ queryKey: queryKeys.decks.all() });
+            },
+        });
+    };
+    /**
+     * Clone a deck into the caller's library (or a space they may change).
+     * The spacer writes the specification again under the new uid.
+     */
+    const useCloneDeck = () => {
+        return useMutation({
+            mutationFn: async (deckId) => {
+                return requestDatalayer({
+                    url: `${configuration.spacerUrl}/api/spacer/v1/decks/${deckId}/clone`,
+                    method: 'POST',
+                });
+            },
+            onSuccess: resp => {
+                if (resp.success && resp.deck) {
+                    const deck = toDeck(resp.deck);
+                    seedDeckDetail(deck);
+                    queryClient.refetchQueries({ queryKey: queryKeys.decks.all() });
+                    queryClient.refetchQueries({ queryKey: queryKeys.items.all() });
+                }
+            },
+        });
+    };
     /**
      * Clone notebook
      */
@@ -2133,191 +2771,51 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             },
         });
     };
-    // ============================================================================
-    // Page Hooks
-    // ============================================================================
-    /**
-     * Get page by ID
-     */
-    const usePage = (pageId) => {
-        return useQuery({
-            queryKey: queryKeys.pages.detail(pageId),
-            queryFn: async () => {
-                const resp = await requestDatalayer({
-                    url: `${configuration.libraryUrl}/api/library/v1/pages/${pageId}`,
-                    method: 'GET',
-                });
-                if (resp.success && resp.page) {
-                    return toPage(resp.page);
-                }
-                throw new Error(resp.message || 'Failed to fetch page');
-            },
-            ...DEFAULT_QUERY_OPTIONS,
-            enabled: !!pageId,
-        });
-    };
     /**
-     * Get all pages
+     * Get all secrets
      */
-    const usePages = (scope) => {
+    // TODO: Previously this hook pre-populated individual secret caches with setQueryData,
+    // but this prevented useSecret from fetching fresh data (e.g., the value field).
+    // Consider re-adding cache pre-population if the list endpoint returns full secret data,
+    // or use a different query key pattern for partial vs full secret data.
+    const useSecrets = (options) => {
+        const principalUid = options?.principalUid;
+        const principalKind = options?.principalKind;
         return useQuery({
             queryKey: [
-                ...queryKeys.pages.all(),
-                scope?.selectedPrincipalUid || '',
-                scope?.selectedPrincipalKind || '',
+                ...queryKeys.secrets.all(),
+                principalUid || 'self',
+                principalKind || '',
             ],
             queryFn: async () => {
-                const params = new URLSearchParams();
-                if (scope?.selectedPrincipalUid) {
-                    params.set('selected_principal_uid', scope.selectedPrincipalUid);
-                }
-                if (scope?.selectedPrincipalKind) {
-                    params.set('selected_principal_kind', scope.selectedPrincipalKind);
-                }
-                const query = params.toString();
                 const resp = await requestDatalayer({
-                    url: `${configuration.libraryUrl}/api/library/v1/pages${query ? `?${query}` : ''}`,
+                    url: withAccountUidQuery(`${configuration.iamUrl}/api/iam/v1/secrets`, principalUid, principalKind),
                     method: 'GET',
                 });
-                if (resp.success && resp.pages) {
-                    const pages = resp.pages
-                        .map((p) => {
-                        const page = toPage(p);
-                        if (page) {
-                            queryClient.setQueryData(queryKeys.pages.detail(page.id), page);
-                        }
-                        return page;
-                    })
+                if (resp.success && resp.secrets) {
+                    const secrets = resp.secrets
+                        .map((s) => toSecret(s))
                         .filter(Boolean);
-                    return pages;
+                    return secrets;
                 }
                 return [];
             },
             ...DEFAULT_QUERY_OPTIONS,
+            refetchOnMount: true, // Override to refetch when stale after invalidation
         });
     };
     /**
-     * Create page
+     * Create secret
      */
-    const useCreatePage = () => {
+    const useCreateSecret = (options) => {
+        const principalUid = options?.principalUid;
+        const principalKind = options?.principalKind;
         return useMutation({
-            mutationFn: async (page) => {
+            mutationFn: async (secret) => {
                 return requestDatalayer({
-                    url: `${configuration.libraryUrl}/api/library/v1/pages`,
+                    url: withAccountUidQuery(`${configuration.iamUrl}/api/iam/v1/secrets`, principalUid, principalKind),
                     method: 'POST',
-                    body: { ...page },
-                });
-            },
-            onSuccess: resp => {
-                if (resp.success && resp.page) {
-                    const page = toPage(resp.page);
-                    if (page) {
-                        // Set detail cache
-                        queryClient.setQueryData(queryKeys.pages.detail(page.id), page);
-                        // Invalidate list to refetch
-                        queryClient.invalidateQueries({
-                            queryKey: queryKeys.pages.all(),
-                        });
-                    }
-                }
-            },
-        });
-    };
-    /**
-     * Update page
-     */
-    const useUpdatePage = () => {
-        return useMutation({
-            mutationFn: async (page) => {
-                return requestDatalayer({
-                    url: `${configuration.libraryUrl}/api/library/v1/pages/${page.id}`,
-                    method: 'PUT',
-                    body: {
-                        name: page.name,
-                        description: page.description,
-                        tags: page.tags,
-                    },
-                });
-            },
-            onSuccess: (resp, page) => {
-                if (resp.success) {
-                    // Invalidate detail and list queries
-                    queryClient.invalidateQueries({
-                        queryKey: queryKeys.pages.detail(page.id),
-                    });
-                    queryClient.invalidateQueries({
-                        queryKey: queryKeys.pages.all(),
-                    });
-                }
-            },
-        });
-    };
-    /**
-     * Delete page
-     */
-    const useDeletePage = () => {
-        return useMutation({
-            mutationFn: async (pageId) => {
-                return requestDatalayer({
-                    url: `${configuration.libraryUrl}/api/library/v1/pages/${pageId}`,
-                    method: 'DELETE',
-                });
-            },
-            onSuccess: (_, pageId) => {
-                // Remove from detail cache
-                queryClient.removeQueries({ queryKey: queryKeys.pages.detail(pageId) });
-                // Invalidate list to refetch
-                queryClient.invalidateQueries({
-                    queryKey: queryKeys.pages.all(),
-                });
-            },
-        });
-    };
-    /**
-     * Get all secrets
-     */
-    // TODO: Previously this hook pre-populated individual secret caches with setQueryData,
-    // but this prevented useSecret from fetching fresh data (e.g., the value field).
-    // Consider re-adding cache pre-population if the list endpoint returns full secret data,
-    // or use a different query key pattern for partial vs full secret data.
-    const useSecrets = (options) => {
-        const principalUid = options?.principalUid;
-        const principalKind = options?.principalKind;
-        return useQuery({
-            queryKey: [
-                ...queryKeys.secrets.all(),
-                principalUid || 'self',
-                principalKind || '',
-            ],
-            queryFn: async () => {
-                const resp = await requestDatalayer({
-                    url: withAccountUidQuery(`${configuration.iamUrl}/api/iam/v1/secrets`, principalUid, principalKind),
-                    method: 'GET',
-                });
-                if (resp.success && resp.secrets) {
-                    const secrets = resp.secrets
-                        .map((s) => toSecret(s))
-                        .filter(Boolean);
-                    return secrets;
-                }
-                return [];
-            },
-            ...DEFAULT_QUERY_OPTIONS,
-            refetchOnMount: true, // Override to refetch when stale after invalidation
-        });
-    };
-    /**
-     * Create secret
-     */
-    const useCreateSecret = (options) => {
-        const principalUid = options?.principalUid;
-        const principalKind = options?.principalKind;
-        return useMutation({
-            mutationFn: async (secret) => {
-                return requestDatalayer({
-                    url: withAccountUidQuery(`${configuration.iamUrl}/api/iam/v1/secrets`, principalUid, principalKind),
-                    method: 'POST',
-                    body: { ...secret },
+                    body: { ...secret },
                 });
             },
             onSuccess: resp => {
@@ -2565,6 +3063,7 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                 queryClient.removeQueries({
                     queryKey: queryKeys.documents.detail(itemId),
                 });
+                queryClient.removeQueries({ queryKey: queryKeys.decks.detail(itemId) });
                 queryClient.removeQueries({ queryKey: queryKeys.cells.detail(itemId) });
                 queryClient.removeQueries({
                     queryKey: queryKeys.lessons.detail(itemId),
@@ -2578,6 +3077,7 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                 // Invalidate all artifact type queries
                 queryClient.invalidateQueries({ queryKey: queryKeys.notebooks.all() });
                 queryClient.invalidateQueries({ queryKey: queryKeys.documents.all() });
+                queryClient.invalidateQueries({ queryKey: queryKeys.decks.all() });
                 queryClient.invalidateQueries({ queryKey: queryKeys.cells.all() });
                 queryClient.invalidateQueries({ queryKey: queryKeys.lessons.all() });
                 queryClient.invalidateQueries({ queryKey: queryKeys.exercises.all() });
@@ -3525,25 +4025,6 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             },
         });
     };
-    /**
-     * Get public courses
-     */
-    const usePublicCourses = () => {
-        return useQuery({
-            queryKey: ['courses', 'public'],
-            queryFn: async () => {
-                const resp = await requestDatalayer({
-                    url: `${configuration.libraryUrl}/api/library/v1/courses/public`,
-                    method: 'GET',
-                });
-                if (resp.success && resp.courses) {
-                    return resp.courses.map((course) => toCourse(course));
-                }
-                return [];
-            },
-            ...DEFAULT_QUERY_OPTIONS,
-        });
-    };
     /**
      * Get instructor courses
      */
@@ -5830,284 +6311,936 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
     /**
      * Search public items (notebooks, documents, etc.)
      */
+    /**
+     * Every artifact type a library card is drawn for. One list, so a caller
+     * that wants "everything" cannot accidentally ask for the six types someone
+     * wrote out by hand two releases ago.
+     *
+     * `deck` is here because the administration page's "not in the ribbon" list
+     * asks for this default: without it a published deck was in the library and
+     * could be found by searching, but was never offered to be featured.
+     */
+    const LIBRARY_ARTIFACT_TYPES = [
+        'notebook',
+        'document',
+        'deck',
+        'cell',
+        'lesson',
+        'exercise',
+        'assignment',
+        'course',
+        'evalset',
+        'dataset',
+        'agent',
+    ];
+    const librarySearchQueryString = ({ q, types, max = 20, offset = 0, sort = 'relevance', featured = false, owner, }) => {
+        const normalizedTypes = Array.from(new Set((types || [])
+            .map(type => String(type || '')
+            .trim()
+            .toLowerCase())
+            .filter(Boolean)
+            .map(type => (type === 'eval' ? 'evalset' : type))));
+        const params = {
+            q: q || '*',
+            types: (normalizedTypes.length > 0
+                ? normalizedTypes
+                : LIBRARY_ARTIFACT_TYPES).join(' '),
+            max: String(max),
+            offset: String(offset),
+            sort,
+        };
+        if (featured) {
+            params.featured = 'true';
+        }
+        if (owner) {
+            params.owner = owner;
+        }
+        return Object.entries(params)
+            .map(([key, value]) => `${key}=${encodeURIComponent(value)}`)
+            .join('&');
+    };
+    const searchLibrary = async (args) => {
+        const resp = await requestDatalayer({
+            url: `${configuration.libraryUrl}/api/library/v1/search?${librarySearchQueryString(args)}`,
+            method: 'GET',
+        });
+        if (!resp.success) {
+            throw new Error(resp.message || 'Failed to search the library');
+        }
+        return {
+            items: (resp.items || [])
+                .map((item) => toItem(item))
+                .filter(Boolean),
+            total: Number(resp.total ?? 0),
+            offset: Number(resp.offset ?? args.offset ?? 0),
+        };
+    };
+    /**
+     * Search the library: one request, whatever mix of artifact types is asked
+     * for, with the total so a caller can page without asking twice.
+     *
+     * Answers `{ items, total, offset }` rather than a bare array — a result
+     * page without its total cannot be paged, and every caller was inventing
+     * "there is probably more" from the length it got.
+     */
     const useSearchPublicItems = () => {
         return useMutation({
-            mutationFn: async ({ q, types = ['notebook', 'document', 'cell', 'lesson', 'evalset', 'course'], max = 100, }) => {
-                const normalizedTypes = Array.from(new Set((types || [])
-                    .map(type => String(type || '')
-                    .trim()
-                    .toLowerCase())
-                    .filter(Boolean)
-                    .map(type => (type === 'eval' ? 'evalset' : type))));
-                const queryString = Object.entries({
-                    q: q || '*',
-                    types: (normalizedTypes.length > 0
-                        ? normalizedTypes
-                        : ['notebook', 'document', 'cell', 'lesson', 'evalset', 'course']).join(' '),
-                    max: max.toString(),
-                })
-                    .map(([key, value]) => `${key}=${encodeURIComponent(value)}`)
-                    .join('&');
+            mutationFn: async (args) => searchLibrary(args),
+        });
+    };
+    /**
+     * Everything the library holds, as a query rather than a mutation.
+     *
+     * For the administration page, which has to show what *could* be featured
+     * as well as what is. Publishing the agent catalogue puts artifacts in the
+     * library; without this the page reported "6 agents published" and then
+     * listed none of them, because the only list it had was the featured one.
+     */
+    const useLibraryArtifacts = (max = 100, options) => {
+        return useQuery({
+            queryKey: [...queryKeys.items.all(), 'library-artifacts', max],
+            queryFn: async () => searchLibrary({ max, sort: 'recent' }),
+            ...options,
+        });
+    };
+    /**
+     * The featured artifacts, for the home page's ribbon.
+     *
+     * Anonymous-safe: the library answers this one without a token, and the
+     * service holds it for a minute, so a visit costs the platform nothing.
+     */
+    const useFeaturedItems = (max = 12, options) => {
+        return useQuery({
+            queryKey: [...queryKeys.items.featured(), max],
+            queryFn: async () => {
                 const resp = await requestDatalayer({
-                    url: `${configuration.libraryUrl}/api/library/v1/search?${queryString}`,
+                    url: `${configuration.libraryUrl}/api/library/v1/featured?max=${max}`,
                     method: 'GET',
                 });
                 if (!resp.success) {
-                    throw new Error(resp.message || 'Failed to search public items');
+                    throw new Error(resp.message || 'Failed to get the featured artifacts');
                 }
                 return (resp.items || [])
                     .map((item) => toItem(item))
                     .filter(Boolean);
             },
+            staleTime: 60_000,
+            ...options,
         });
     };
-    // ============================================================================
-    // Social Media Integrations
-    // ============================================================================
     /**
-     * Get GitHub profile from access token
-     */
-    const useGetGitHubProfile = () => {
-        return useMutation({
-            mutationFn: async (accessToken) => {
-                const response = await fetch('https://api.github.com/user', {
+     * Everything an administrator has actually featured, and nothing else.
+     *
+     * Not `useFeaturedItems`. That one answers for the home page's ribbon: a
+     * public request, capped at what a row can show, ordered for reading. This
+     * one is what the administration page edits — everything featured, in rank
+     * order, however long the list is and whoever it belongs to — so that the
+     * page showing the ribbon's contents is showing the ribbon's contents and
+     * not a page of it. `platform_admin` only.
+     */
+    const useAllFeaturedItems = (options) => {
+        return useQuery({
+            queryKey: [...queryKeys.items.featured(), 'all'],
+            queryFn: async () => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/featured/all`,
                     method: 'GET',
-                    headers: {
-                        Accept: 'application/vnd.github+json',
-                        Authorization: `Bearer ${accessToken}`,
-                        'X-GitHub-Api-Version': '2022-11-28',
-                    },
                 });
-                return response.json();
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to get the featured artifacts');
+                }
+                return (resp.items || [])
+                    .map((item) => toItem(item))
+                    .filter(Boolean);
             },
+            ...options,
         });
     };
     /**
-     * Get Google profile from access token
+     * One public artifact by uid, with its content and its library metadata.
+     *
+     * The public pages used to `fetch` this endpoint themselves, which meant no
+     * token was ever sent and the page could not know whether the visitor
+     * orbits what they are reading.
      */
-    const useGetGoogleProfile = () => {
-        return useMutation({
-            mutationFn: async (accessToken) => {
-                const response = await fetch('https://openidconnect.googleapis.com/v1/userinfo', {
+    const usePublicItem = (itemId, options) => {
+        return useQuery({
+            queryKey: queryKeys.items.publicItem(itemId || ''),
+            queryFn: async () => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/public/items/${encodeURIComponent(itemId)}`,
                     method: 'GET',
-                    headers: {
-                        Accept: 'application/json',
-                        Authorization: `Bearer ${accessToken}`,
-                    },
                 });
-                return response.json();
+                if (!resp.success || !resp.item) {
+                    throw new Error(resp.message || 'Failed to get the public artifact');
+                }
+                return toItem(resp.item);
             },
+            enabled: Boolean(itemId),
+            ...options,
         });
     };
-    /**
-     * Get LinkedIn profile via proxy
-     */
-    const useGetLinkedinProfile = () => {
-        return useMutation({
-            mutationFn: async (accessToken) => {
-                return requestDatalayer({
-                    url: `${configuration.iamUrl}/api/iam/v1/proxy/request`,
-                    method: 'POST',
-                    body: {
-                        request_method: 'GET',
-                        request_url: 'https://api.linkedin.com/v2/userinfo',
-                        request_token: accessToken,
-                    },
+    /** The artifacts this account has published: a public profile page. */
+    const useAccountPublications = (handle, options) => {
+        return useQuery({
+            queryKey: queryKeys.items.byOwner(handle || ''),
+            queryFn: async () => searchLibrary({ owner: handle, max: 100, sort: 'recent' }),
+            enabled: Boolean(handle),
+            ...options,
+        });
+    };
+    /** The artifacts the signed-in visitor orbits. */
+    const useMyOrbits = (offset = 0, max = 20, options) => {
+        return useQuery({
+            queryKey: [...queryKeys.items.orbits(), offset, max],
+            queryFn: async () => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/orbits?offset=${offset}&max=${max}`,
+                    method: 'GET',
                 });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to get the orbits');
+                }
+                return {
+                    items: (resp.items || [])
+                        .map((item) => toItem(item))
+                        .filter(Boolean),
+                    total: Number(resp.total ?? 0),
+                };
             },
+            ...options,
         });
     };
     /**
-     * Post LinkedIn share
+     * What one account orbits, on its public profile.
+     *
+     * Whether it publishes them at all is the service's answer, not this
+     * caller's: `shown` says so, and an account that has not opted in reads the
+     * same as one that orbits nothing.
      */
-    const usePostLinkedinShare = () => {
-        return useMutation({
-            mutationFn: async ({ linkedinUserUrn, postText, accessToken, }) => {
-                const postShareRequest = {
-                    author: linkedinUserUrn,
-                    lifecycleState: 'PUBLISHED',
-                    specificContent: {
-                        'com.linkedin.ugc.ShareContent': {
-                            shareCommentary: { text: postText },
-                            shareMediaCategory: 'NONE',
-                        },
-                    },
-                    visibility: {
-                        'com.linkedin.ugc.MemberNetworkVisibility': 'PUBLIC',
-                    },
+    const useAccountOrbits = (handle, offset = 0, max = 12, options) => {
+        return useQuery({
+            queryKey: [
+                ...queryKeys.items.orbits(),
+                'account',
+                handle || '',
+                offset,
+                max,
+            ],
+            queryFn: async () => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/accounts/${encodeURIComponent(handle)}/orbits?offset=${offset}&max=${max}`,
+                    method: 'GET',
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to get the orbits');
+                }
+                return {
+                    items: (resp.items || [])
+                        .map((item) => toItem(item))
+                        .filter(Boolean),
+                    total: Number(resp.total ?? 0),
+                    shown: Boolean(resp.shown),
                 };
-                return requestDatalayer({
-                    url: `${configuration.iamUrl}/api/iam/v1/proxy/request`,
-                    method: 'POST',
-                    body: {
-                        request_method: 'POST',
-                        request_url: 'https://api.linkedin.com/v2/ugcPosts',
-                        request_token: accessToken,
-                        request_body: postShareRequest,
-                    },
+            },
+            enabled: Boolean(handle),
+            ...options,
+        });
+    };
+    /** Who orbits an artifact. */
+    const useItemOrbiters = (itemId, offset = 0, max = 20, options) => {
+        return useQuery({
+            queryKey: [
+                ...queryKeys.items.orbiters(itemId || ''),
+                offset,
+                max,
+            ],
+            queryFn: async () => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/items/${encodeURIComponent(itemId)}/orbiters?offset=${offset}&max=${max}`,
+                    method: 'GET',
                 });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to get the orbiters');
+                }
+                return {
+                    orbiters: resp.orbiters || [],
+                    total: Number(resp.total ?? 0),
+                };
             },
+            enabled: Boolean(itemId),
+            ...options,
         });
     };
     /**
-     * Post LinkedIn share with image upload
+     * What was made of a public artifact (B5-04): every derivation counted by
+     * kind, and the derived artifacts that are public themselves, newest first.
      */
-    const usePostLinkedinShareWithUpload = () => {
-        return useMutation({
-            mutationFn: async ({ linkedinUserUrn, postText, uploadObject, accessToken, }) => {
-                let shareRequest;
-                if (uploadObject) {
-                    // Step 1: Register upload
-                    const registerUploadRequest = {
-                        registerUploadRequest: {
-                            recipes: ['urn:li:digitalmediaRecipe:feedshare-image'],
-                            owner: linkedinUserUrn,
-                            serviceRelationships: [
-                                {
-                                    relationshipType: 'OWNER',
-                                    identifier: 'urn:li:userGeneratedContent',
-                                },
-                            ],
-                        },
-                    };
-                    const registerResp = await requestDatalayer({
-                        url: `${configuration.iamUrl}/api/iam/v1/proxy/request`,
-                        method: 'POST',
-                        body: {
-                            request_method: 'POST',
-                            request_url: 'https://api.linkedin.com/v2/assets?action=registerUpload',
-                            request_token: accessToken,
-                            request_body: registerUploadRequest,
-                        },
-                    });
-                    const asset = registerResp.response.value.asset;
-                    const uploadUrl = registerResp.response.value.uploadMechanism['com.linkedin.digitalmedia.uploading.MediaUploadHttpRequest'].uploadUrl;
-                    // Step 2: Upload image
-                    await requestDatalayer({
-                        url: `${configuration.iamUrl}/api/iam/v1/proxy/request`,
-                        method: 'POST',
-                        body: {
-                            request_method: 'PUT',
-                            request_url: uploadUrl,
-                            request_token: accessToken,
-                            request_body: {
-                                uploadURL: uploadUrl,
-                                content: uploadObject,
-                                userURN: linkedinUserUrn,
-                            },
-                        },
-                    });
-                    // Step 3: Create share with media
-                    shareRequest = {
-                        author: linkedinUserUrn,
-                        lifecycleState: 'PUBLISHED',
-                        specificContent: {
-                            'com.linkedin.ugc.ShareContent': {
-                                shareCommentary: { text: postText },
-                                shareMediaCategory: 'IMAGE',
-                                media: [
-                                    {
-                                        status: 'READY',
-                                        description: { text: 'Datalayer Notebook' },
-                                        media: asset,
-                                        title: { text: 'Datalayer Notebook' },
-                                    },
-                                ],
-                            },
-                        },
-                        visibility: {
-                            'com.linkedin.ugc.MemberNetworkVisibility': 'PUBLIC',
-                        },
-                    };
+    const useItemDerivations = (itemId, offset = 0, max = 20, options) => {
+        return useQuery({
+            queryKey: [
+                ...queryKeys.items.derivations(itemId || ''),
+                offset,
+                max,
+            ],
+            queryFn: async () => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/items/${encodeURIComponent(itemId)}/derivations?offset=${offset}&max=${max}`,
+                    method: 'GET',
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to get the derivations');
                 }
-                else {
-                    // Text-only share (no image upload)
-                    shareRequest = {
-                        author: linkedinUserUrn,
-                        lifecycleState: 'PUBLISHED',
-                        specificContent: {
-                            'com.linkedin.ugc.ShareContent': {
-                                shareCommentary: { text: postText },
-                                shareMediaCategory: 'NONE',
-                            },
-                        },
-                        visibility: {
-                            'com.linkedin.ugc.MemberNetworkVisibility': 'PUBLIC',
-                        },
-                    };
+                return {
+                    derivations: (resp.derivations || []).map((derivation) => ({
+                        kind: String(derivation.kind || ''),
+                        fromVersion: derivation.fromVersion ?? null,
+                        derivedAt: derivation.derivedAt,
+                        item: toItem(derivation.item),
+                    })),
+                    counts: (resp.counts || {}),
+                    total: Number(resp.total ?? 0),
+                };
+            },
+            enabled: Boolean(itemId),
+            ...options,
+        });
+    };
+    /**
+     * Show an artifact as orbited before the server has said so, and put it
+     * back if the server disagrees.
+     *
+     * A star that waits for a round trip feels broken, and the count is on the
+     * button the visitor just pressed. The server answers with a recount, which
+     * is what finally lands in the cache.
+     */
+    const applyOrbitToCaches = (itemId, orbited, orbits) => {
+        const patch = (item) => {
+            if (!item || String(item.id ?? item.uid) !== String(itemId)) {
+                return item;
+            }
+            const nextOrbits = orbits !== undefined
+                ? orbits
+                : Math.max(0, Number(item.orbits || 0) + (orbited ? 1 : -1));
+            return { ...item, orbited, orbits: nextOrbits };
+        };
+        queryClient.setQueriesData({ queryKey: queryKeys.items.all() }, (data) => {
+            if (!data) {
+                return data;
+            }
+            if (Array.isArray(data)) {
+                return data.map(patch);
+            }
+            if (Array.isArray(data.items)) {
+                return { ...data, items: data.items.map(patch) };
+            }
+            if (data.id || data.uid) {
+                return patch(data);
+            }
+            return data;
+        });
+    };
+    const useOrbitItem = () => {
+        return useMutation({
+            mutationFn: async (itemId) => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/items/${encodeURIComponent(itemId)}/orbit`,
+                    method: 'PUT',
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to orbit the artifact');
                 }
-                return requestDatalayer({
-                    url: `${configuration.iamUrl}/api/iam/v1/proxy/request`,
+                return { itemId, orbits: Number(resp.orbits ?? 0), orbited: true };
+            },
+            onMutate: async (itemId) => {
+                applyOrbitToCaches(itemId, true);
+                return { itemId };
+            },
+            onError: (_error, itemId) => {
+                applyOrbitToCaches(itemId, false);
+            },
+            onSuccess: result => {
+                applyOrbitToCaches(result.itemId, true, result.orbits);
+                queryClient.invalidateQueries({ queryKey: queryKeys.items.orbits() });
+            },
+        });
+    };
+    const useUnorbitItem = () => {
+        return useMutation({
+            mutationFn: async (itemId) => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/items/${encodeURIComponent(itemId)}/orbit`,
+                    method: 'DELETE',
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to leave the orbit');
+                }
+                return { itemId, orbits: Number(resp.orbits ?? 0), orbited: false };
+            },
+            onMutate: async (itemId) => {
+                applyOrbitToCaches(itemId, false);
+                return { itemId };
+            },
+            onError: (_error, itemId) => {
+                applyOrbitToCaches(itemId, true);
+            },
+            onSuccess: result => {
+                applyOrbitToCaches(result.itemId, false, result.orbits);
+                queryClient.invalidateQueries({ queryKey: queryKeys.items.orbits() });
+            },
+        });
+    };
+    /** Feature an artifact on the home page. `platform_admin` only. */
+    const useFeatureItem = () => {
+        return useMutation({
+            mutationFn: async ({ itemId, rank, }) => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/items/${encodeURIComponent(itemId)}/featured`,
+                    method: 'PUT',
+                    body: { rank: rank ?? null },
+                    // One toast, not two: the caller says which artifact failed and
+                    // why, so the generic report underneath is a duplicate.
+                    notifyOnError: false,
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to feature the artifact');
+                }
+                return resp;
+            },
+            onSuccess: () => {
+                invalidateEverywhere(queryClient, queryKeys.items.all());
+            },
+        });
+    };
+    const useUnfeatureItem = () => {
+        return useMutation({
+            mutationFn: async (itemId) => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/items/${encodeURIComponent(itemId)}/featured`,
+                    method: 'DELETE',
+                    // One toast, not two: the caller says which artifact failed and
+                    // why, so the generic report underneath is a duplicate.
+                    notifyOnError: false,
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to unfeature the artifact');
+                }
+                return resp;
+            },
+            onSuccess: () => {
+                invalidateEverywhere(queryClient, queryKeys.items.all());
+            },
+        });
+    };
+    const useSetFeaturedRank = () => {
+        return useMutation({
+            mutationFn: async ({ itemId, rank, }) => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/items/${encodeURIComponent(itemId)}/featured`,
+                    method: 'PATCH',
+                    body: { rank },
+                    // One toast, not two: the caller says which artifact failed and
+                    // why, so the generic report underneath is a duplicate.
+                    notifyOnError: false,
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to move the artifact');
+                }
+                return resp;
+            },
+            onSuccess: () => {
+                invalidateEverywhere(queryClient, queryKeys.items.featured());
+            },
+        });
+    };
+    /**
+     * Refresh everything that carries an artifact's public flag or its image.
+     *
+     * `items` and `spaces` cover the library listings, but an artifact opened in
+     * an editor is read through its own per-type query — `notebooks.detail(id)`
+     * for the editor, `notebooks.bySpace(id)` for the table — and neither
+     * shares a prefix with either of those. Leaving them alone is what made the
+     * Publish button keep saying "Publish" after publishing, and "Published"
+     * after withdrawing: the mutation succeeded, the cached copy still held the
+     * old `is_public_b`, and nothing asked for it again for five minutes.
+     *
+     * A course is a space, but it is not read through the `spaces` queries: it
+     * has a namespace of its own, so publishing one from its header left the
+     * course page holding the `public` flag it loaded with and the button
+     * saying the opposite of what had just happened.
+     *
+     * **`refetchType: 'all'`, which is what makes any of the above work.**
+     *
+     * Naming a query is not the same as making it ask again. The default,
+     * `'active'`, refetches the queries something is currently watching and
+     * leaves the rest marked stale — right nearly everywhere, and wrong here,
+     * because this application sets `refetchOnMount: false` (see
+     * `DEFAULT_QUERY_OPTIONS`, and the client the web application builds). A
+     * query that mounts holding stale data renders it and asks for nothing.
+     *
+     * So publishing worked exactly once. The editor it was published from was
+     * mounted and flipped its button; the notebooks table, the library, the
+     * search page and the artifact's own public page were not, and kept the
+     * answer they already had. Come back to the editor after that and *it* is
+     * now the page that was not mounted for the next withdrawal, so its button
+     * is wrong too — which is what "it works the first time" means.
+     *
+     * The whole of each type's namespace, not only its `details()`. A table
+     * lists its artifacts under `bySpace(spaceId)`, which shares no prefix with
+     * `detail(id)` — so publishing from an editor and walking back to the table
+     * showed the row exactly as it was, switch and all.
+     *
+     * The `model` queries are the one thing held out. A notebook's model is its
+     * content, megabytes of it, and it lives *under* `detail(id)` — so
+     * refetching a namespace would pull every open notebook's content over the
+     * wire each time somebody pressed Publish. Whether an artifact is public
+     * says nothing about what is in it.
+     */
+    const invalidateArtifactVisibility = () => {
+        const refetchType = 'all';
+        /** Everything about an artifact except what is written in it. */
+        const notItsContent = (query) => query.queryKey[query.queryKey.length - 1] !== 'model';
+        queryClient.invalidateQueries({
+            queryKey: queryKeys.items.all(),
+            refetchType,
+        });
+        queryClient.invalidateQueries({ queryKey: ['spaces'], refetchType });
+        for (const namespace of [
+            queryKeys.notebooks.all(),
+            queryKeys.documents.all(),
+            queryKeys.decks.all(),
+            queryKeys.cells.all(),
+            queryKeys.lessons.all(),
+            queryKeys.exercises.all(),
+            queryKeys.assignments.all(),
+            queryKeys.courses.all(),
+        ]) {
+            queryClient.invalidateQueries({
+                queryKey: namespace,
+                refetchType,
+                predicate: notItsContent,
+            });
+        }
+    };
+    /**
+     * What an artifact looks like in the library: a capture the publisher took,
+     * the box drawn for its kind, or an icon from the Datalayer set.
+     */
+    const useSetItemImage = () => {
+        return useMutation({
+            mutationFn: async ({ itemId, kind, ref, data, }) => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/items/${encodeURIComponent(itemId)}/image`,
+                    method: 'PUT',
+                    body: { kind, ref, data },
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to set the image');
+                }
+                return resp.image;
+            },
+            onSuccess: invalidateArtifactVisibility,
+        });
+    };
+    const useResetItemImage = () => {
+        return useMutation({
+            mutationFn: async (itemId) => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/items/${encodeURIComponent(itemId)}/image`,
+                    method: 'DELETE',
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to reset the image');
+                }
+                return resp.image;
+            },
+            onSuccess: invalidateArtifactVisibility,
+        });
+    };
+    /** Publish a public artifact natively to LinkedIn through Library's saga. */
+    const usePublishLinkedInShare = () => {
+        return useMutation({
+            mutationFn: async ({ itemId, commentary, idempotencyKey, imageDataUrl, imageAltText, }) => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/items/${encodeURIComponent(itemId)}/shares/linkedin`,
+                    method: 'POST',
+                    headers: { 'Idempotency-Key': idempotencyKey },
+                    body: { commentary, imageDataUrl, imageAltText },
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to publish to LinkedIn');
+                }
+                return resp.share;
+            },
+        });
+    };
+    const useUnpublishLinkedInShare = () => {
+        return useMutation({
+            mutationFn: async (idempotencyKey) => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/shares/linkedin/${encodeURIComponent(idempotencyKey)}`,
+                    method: 'DELETE',
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to unpublish from LinkedIn');
+                }
+                return resp.share;
+            },
+        });
+    };
+    const useLinkedInShares = (itemId, enabled = true) => {
+        return useQuery({
+            queryKey: ['library', 'social-shares', 'linkedin', itemId],
+            queryFn: async () => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/items/${encodeURIComponent(itemId)}/shares/linkedin`,
+                    method: 'GET',
+                    notifyOnError: false,
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to load LinkedIn publications');
+                }
+                return Array.isArray(resp.shares) ? resp.shares : [];
+            },
+            ...DEFAULT_QUERY_OPTIONS,
+            enabled: Boolean(configuration.libraryUrl) && Boolean(itemId) && enabled,
+        });
+    };
+    /** Publish one selected public result through the durable Bluesky saga. */
+    const usePublishBlueskyShare = () => {
+        return useMutation({
+            mutationFn: async ({ itemId, finding, cellId, outputIndex, idempotencyKey, imageDataUrl, imageAltText, }) => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/items/${encodeURIComponent(itemId)}/shares/bluesky`,
+                    method: 'POST',
+                    headers: { 'Idempotency-Key': idempotencyKey },
+                    body: { finding, cellId, outputIndex, imageDataUrl, imageAltText },
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to publish to Bluesky');
+                }
+                return resp.share;
+            },
+        });
+    };
+    const useUnpublishBlueskyShare = () => {
+        return useMutation({
+            mutationFn: async (idempotencyKey) => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/shares/bluesky/${encodeURIComponent(idempotencyKey)}`,
+                    method: 'DELETE',
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to unpublish from Bluesky');
+                }
+                return resp.share;
+            },
+        });
+    };
+    const useBlueskyShares = (itemId, enabled = true) => {
+        return useQuery({
+            queryKey: ['library', 'social-shares', 'bluesky', itemId],
+            queryFn: async () => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/items/${encodeURIComponent(itemId)}/shares/bluesky`,
+                    method: 'GET',
+                    notifyOnError: false,
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to load Bluesky publications');
+                }
+                return Array.isArray(resp.shares) ? resp.shares : [];
+            },
+            ...DEFAULT_QUERY_OPTIONS,
+            enabled: Boolean(configuration.libraryUrl) && Boolean(itemId) && enabled,
+        });
+    };
+    /**
+     * Tell the library that an artifact was reused: cloned into a space, or
+     * instantiated as a runtime. The reuse itself belongs to the service that
+     * performed it, so this is a count, not the act.
+     */
+    const useCountItemReuse = () => {
+        return useMutation({
+            mutationFn: async ({ itemId, kind, signupSource, shareRef, }) => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/items/${encodeURIComponent(itemId)}/reused`,
                     method: 'POST',
                     body: {
-                        request_method: 'POST',
-                        request_url: 'https://api.linkedin.com/v2/ugcPosts',
-                        request_token: accessToken,
-                        request_body: shareRequest,
+                        kind,
+                        ...(signupSource && shareRef ? { signupSource, shareRef } : {}),
                     },
                 });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to count the reuse');
+                }
+                return resp;
             },
         });
     };
-    // ============================================================================
-    // Proxy Operations
-    // ============================================================================
     /**
-     * Proxy GET request
+     * Publish the platform's own catalogue — the agents — into the library.
+     * `platform_admin` only; the catalogue lives in this application's build.
      */
-    const useProxyGET = () => {
+    const useSyncArtifactCatalogue = () => {
         return useMutation({
-            mutationFn: async ({ url, token }) => {
-                return requestDatalayer({
-                    url: `${configuration.iamUrl}/api/iam/v1/proxy/request`,
-                    method: 'POST',
+            mutationFn: async ({ artifacts, artifactType = 'agent', }) => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/artifacts/sync`,
+                    method: 'PUT',
+                    body: { artifact_type: artifactType, artifacts },
+                    // One toast, not two: the caller says which artifact failed and
+                    // why, so the generic report underneath is a duplicate.
+                    notifyOnError: false,
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to synchronize the catalogue');
+                }
+                return resp;
+            },
+            onSuccess: () => {
+                invalidateEverywhere(queryClient, queryKeys.items.all());
+            },
+        });
+    };
+    /**
+     * Publish an artifact in the library: choose its image, then make it
+     * public.
+     *
+     * The one place that publishes. It used to be a `ToggleSwitch` in each of
+     * seven tables and three editors, each with its own copy of the mutation
+     * and its own idea of what to roll back; publishing is an act with
+     * consequences a switch cannot express — a picture to choose, a public page
+     * that appears, a search it enters.
+     *
+     * The image is set first: a failure there leaves the artifact private, which
+     * is recoverable by trying again, where the reverse would publish something
+     * showing the wrong picture.
+     */
+    const usePublishArtifact = () => {
+        const setImage = useSetItemImage();
+        return useMutation({
+            mutationFn: async ({ itemId, image, tags, description, }) => {
+                /*
+                 * Publish first, then dress it.
+                 *
+                 * The image used to be set before the artifact was made public, so
+                 * that a picture that would not take left it private rather than
+                 * published with the wrong one. That order could never work: the
+                 * library indexes public artifacts, so a private one has no
+                 * projection, and setting an image on it answered "The artifact is
+                 * not found" — every first publish with a picture failed.
+                 *
+                 * The intent survives the reordering. The artifact goes public, which
+                 * is what creates the projection; if the picture then will not take,
+                 * it is withdrawn again and the message still tells the truth.
+                 */
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/items/${encodeURIComponent(itemId)}/public`,
+                    method: 'PATCH',
                     body: {
-                        request_method: 'GET',
-                        request_url: url,
-                        request_token: token,
+                        is_public: true,
+                        // Absent, not null: the service reads "leave it alone" from a
+                        // missing key, and a caller that does not know an artifact's
+                        // words must not be able to clear them by omission.
+                        ...(tags === undefined ? {} : { tags }),
+                        ...(description === undefined ? {} : { description }),
                     },
                 });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to publish the artifact');
+                }
+                if (image) {
+                    try {
+                        await setImage.mutateAsync({ itemId, ...image });
+                    }
+                    catch (error) {
+                        // Back to private, so the artifact is never left public wearing
+                        // the drawing the publisher did not choose.
+                        try {
+                            await requestDatalayer({
+                                url: `${configuration.libraryUrl}/api/library/v1/items/${encodeURIComponent(itemId)}/public`,
+                                method: 'PATCH',
+                                body: { is_public: false },
+                            });
+                        }
+                        catch {
+                            // The withdrawal failed too; the error below is still the one
+                            // worth showing, and it is the more actionable of the two.
+                        }
+                        throw new Error(`The image could not be set, so the artifact stays private: ${error?.message || 'unknown error'}`, { cause: error });
+                    }
+                }
+                return resp;
             },
+            onSuccess: invalidateArtifactVisibility,
         });
     };
     /**
-     * Proxy POST request
+     * Withdraw an artifact from the library. Its orbits are kept: publishing it
+     * again brings them back.
      */
-    const useProxyPOST = () => {
+    /**
+     * Rename a published artifact, or change what it says about itself.
+     *
+     * The words belong to the artifact rather than to the library — the
+     * library holds a projection of them — so the library service writes the
+     * artifact's own source and that write carries the change into the index.
+     * Which is why this is one request and not two.
+     *
+     * Every field is optional and every one means "leave it alone" when
+     * omitted, so a caller may change one without knowing the others.
+     */
+    const useUpdateArtifactDetails = () => {
         return useMutation({
-            mutationFn: async ({ url, body, token, }) => {
-                return requestDatalayer({
-                    url: `${configuration.iamUrl}/api/iam/v1/proxy/request`,
-                    method: 'POST',
+            mutationFn: async ({ itemId, name, description, tags, }) => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/items/${encodeURIComponent(itemId)}`,
+                    method: 'PATCH',
                     body: {
-                        request_method: 'POST',
-                        request_url: url,
-                        request_token: token,
-                        request_body: body,
+                        ...(name === undefined ? {} : { name }),
+                        ...(description === undefined ? {} : { description }),
+                        ...(tags === undefined ? {} : { tags }),
+                    },
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to update the artifact');
+                }
+                return resp;
+            },
+            // The same fan-out publishing uses: a rename changes the card in every
+            // listing, the editor's own copy, and the artifact's public page.
+            onSuccess: invalidateArtifactVisibility,
+        });
+    };
+    const useUnpublishArtifact = () => {
+        return useMutation({
+            mutationFn: async (itemId) => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/items/${encodeURIComponent(itemId)}/public`,
+                    method: 'PATCH',
+                    body: { is_public: false },
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to withdraw the artifact');
+                }
+                return resp;
+            },
+            onSuccess: invalidateArtifactVisibility,
+        });
+    };
+    // ============================================================================
+    // Social Media Integrations
+    // ============================================================================
+    /**
+     * Get GitHub profile from access token
+     */
+    const useGetGitHubProfile = () => {
+        return useMutation({
+            mutationFn: async (accessToken) => {
+                const response = await fetch('https://api.github.com/user', {
+                    method: 'GET',
+                    headers: {
+                        Accept: 'application/vnd.github+json',
+                        Authorization: `Bearer ${accessToken}`,
+                        'X-GitHub-Api-Version': '2022-11-28',
                     },
                 });
+                return response.json();
             },
         });
     };
     /**
-     * Proxy PUT request
+     * Get Google profile from access token
      */
-    const useProxyPUT = () => {
+    const useGetGoogleProfile = () => {
+        return useMutation({
+            mutationFn: async (accessToken) => {
+                const response = await fetch('https://openidconnect.googleapis.com/v1/userinfo', {
+                    method: 'GET',
+                    headers: {
+                        Accept: 'application/json',
+                        Authorization: `Bearer ${accessToken}`,
+                    },
+                });
+                return response.json();
+            },
+        });
+    };
+    /** Get the server-connected LinkedIn profile. */
+    const useGetLinkedinProfile = () => {
+        return useMutation({
+            mutationFn: async () => {
+                return requestDatalayer({
+                    url: `${configuration.iamUrl}/api/iam/v1/social/linkedin/profile`,
+                    method: 'GET',
+                });
+            },
+        });
+    };
+    /** Publish a LinkedIn text post through the server-held connection. */
+    const usePostLinkedinShare = () => {
+        return useMutation({
+            mutationFn: async ({ postText }) => {
+                return requestDatalayer({
+                    url: `${configuration.iamUrl}/api/iam/v1/social/linkedin/posts`,
+                    method: 'POST',
+                    body: { commentary: postText },
+                });
+            },
+        });
+    };
+    /** Publish a LinkedIn post, optionally with one uploaded image. */
+    const usePostLinkedinShareWithUpload = () => {
         return useMutation({
-            mutationFn: async ({ url, body, token, }) => {
+            mutationFn: async ({ postText, uploadObject, }) => {
                 return requestDatalayer({
-                    url: `${configuration.iamUrl}/api/iam/v1/proxy/request`,
+                    url: `${configuration.iamUrl}/api/iam/v1/social/linkedin/posts`,
                     method: 'POST',
                     body: {
-                        request_method: 'PUT',
-                        request_url: url,
-                        request_token: token,
-                        request_body: body,
+                        commentary: postText,
+                        image_data_url: uploadObject,
                     },
                 });
             },
         });
     };
+    /** Connect-only AT Protocol account operations. */
+    const useGetBlueskyConnection = () => useMutation({
+        mutationFn: async () => requestDatalayer({
+            url: `${configuration.iamUrl}/api/iam/v1/social/bluesky/profile`,
+            method: 'GET',
+            notifyOnError: false,
+        }),
+    });
+    /**
+     * Begin a Bluesky connection.
+     *
+     * `returnOrigin` is where the reader should come back to — their own origin,
+     * so a connection begun on a developer's machine does not end on
+     * production. IAM takes the origin only and builds the address itself, so
+     * this cannot ask to be sent anywhere.
+     */
+    const useConnectBluesky = () => useMutation({
+        mutationFn: async (asked) => {
+            const { identifier, returnOrigin } = typeof asked === 'string'
+                ? { identifier: asked, returnOrigin: undefined }
+                : asked;
+            return requestDatalayer({
+                url: `${configuration.iamUrl}/api/iam/v1/social/bluesky/connect`,
+                method: 'POST',
+                body: returnOrigin
+                    ? { identifier, return_origin: returnOrigin }
+                    : { identifier },
+            });
+        },
+    });
+    const useDisconnectBluesky = () => useMutation({
+        mutationFn: async () => requestDatalayer({
+            url: `${configuration.iamUrl}/api/iam/v1/social/bluesky/connection`,
+            method: 'DELETE',
+        }),
+    });
     // ============================================================================
     // Waiting List & Growth
     // ============================================================================
@@ -6215,28 +7348,6 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             ...options,
         });
     };
-    /**
-     * Refresh public courses list
-     * @param options - Mutation options
-     */
-    const useRefreshPublicCourses = (options) => {
-        const queryClient = useQueryClient();
-        return useMutation({
-            mutationFn: async () => {
-                const resp = await requestDatalayer({
-                    url: `${configuration.libraryUrl}/api/library/v1/courses/public`,
-                    method: 'GET',
-                });
-                return resp;
-            },
-            onSuccess: () => {
-                queryClient.invalidateQueries({
-                    queryKey: queryKeys.courses.public(),
-                });
-            },
-            ...options,
-        });
-    };
     /**
      * Refresh instructor courses list
      * @param options - Mutation options
@@ -6465,28 +7576,6 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             ...options,
         });
     };
-    /**
-     * Get public items (query hook)
-     * @param options - Query options
-     */
-    const usePublicItems = (options) => {
-        return useQuery({
-            queryKey: queryKeys.items.public(),
-            queryFn: async () => {
-                const resp = await requestDatalayer({
-                    url: `${configuration.libraryUrl}/api/library/v1/search?q=*&max=-1`,
-                    method: 'GET',
-                });
-                return {
-                    ...resp,
-                    items: (resp.items || [])
-                        .map((item) => toItem(item))
-                        .filter(Boolean),
-                };
-            },
-            ...options,
-        });
-    };
     /**
      * Get the current user's own public items (publications).
      * @param options - Query options
@@ -6509,31 +7598,6 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             ...options,
         });
     };
-    /**
-     * Refresh public items
-     * @param options - Mutation options
-     */
-    const useRefreshPublicItems = (options) => {
-        const queryClient = useQueryClient();
-        return useMutation({
-            mutationFn: async () => {
-                const resp = await requestDatalayer({
-                    url: `${configuration.libraryUrl}/api/library/v1/search?q=*&max=-1`,
-                    method: 'GET',
-                });
-                return {
-                    ...resp,
-                    items: (resp.items || [])
-                        .map((item) => toItem(item))
-                        .filter(Boolean),
-                };
-            },
-            onSuccess: () => {
-                queryClient.invalidateQueries({ queryKey: queryKeys.items.public() });
-            },
-            ...options,
-        });
-    };
     /**
      * Refresh space items
      * @param options - Mutation options
@@ -7225,11 +8289,16 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
         useGetLinkedinProfile,
         usePostLinkedinShare,
         usePostLinkedinShareWithUpload,
+        useGetBlueskyConnection,
+        useConnectBluesky,
+        useDisconnectBluesky,
+        usePublishLinkedInShare,
+        useUnpublishLinkedInShare,
+        useLinkedInShares,
+        usePublishBlueskyShare,
+        useUnpublishBlueskyShare,
+        useBlueskyShares,
         useRegisterToWaitingList,
-        // Proxy
-        useProxyGET,
-        useProxyPOST,
-        useProxyPUT,
         // Users
         useUser,
         useUserByHandle,
@@ -7311,7 +8380,6 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
         // Courses
         useCourse,
         useUpdateCourse,
-        usePublicCourses,
         useInstructorCourses,
         useCourseEnrollments,
         useEnrollStudentToCourse,
@@ -7321,7 +8389,6 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
         useConfirmCourseItemCompletion,
         useSetCourseItems,
         useRefreshCourse,
-        useRefreshPublicCourses,
         useRefreshInstructorCourses,
         useRefreshCoursesEnrollments,
         useRefreshStudent,
@@ -7334,6 +8401,13 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
         useCloneNotebook,
         useRefreshNotebook,
         useRefreshSpaceNotebooks,
+        // Decks
+        useDeck,
+        useDecksBySpace,
+        useCreateDeck,
+        useUpdateDeck,
+        useUpdateDeckModel,
+        useCloneDeck,
         // Documents
         useDocument,
         useDocumentsBySpace,
@@ -7387,18 +8461,33 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
         useMakeItemPublic,
         useMakeItemPrivate,
         useSearchPublicItems,
-        usePublicItems,
+        useLibraryArtifacts,
         usePublications,
-        useRefreshPublicItems,
+        // Library (search, orbits, featuring, images, reuse)
+        useFeaturedItems,
+        useAllFeaturedItems,
+        usePublicItem,
+        useAccountPublications,
+        useMyOrbits,
+        useAccountOrbits,
+        useItemOrbiters,
+        useItemDerivations,
+        useOrbitItem,
+        useUnorbitItem,
+        useFeatureItem,
+        useUnfeatureItem,
+        useSetFeaturedRank,
+        useSetItemImage,
+        useResetItemImage,
+        useCountItemReuse,
+        useSyncArtifactCatalogue,
+        usePublishArtifact,
+        useUnpublishArtifact,
+        useUpdateArtifactDetails,
         useRefreshSpaceItems,
         useClearCachedPublicItems,
         useClearCachedItems,
         // Pages
-        usePage,
-        usePages,
-        useCreatePage,
-        useUpdatePage,
-        useDeletePage,
         // Secrets
         useSecret,
         useSecrets,
@@ -7497,6 +8586,9 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
         documentUploadLoading,
         documentUploadProgress,
         resetDocumentUpload,
+        deckUploadLoading,
+        deckUploadProgress,
+        resetDeckUpload,
     };
 };
 export default useCache;