@datalayer/core 1.2.23 → 1.2.24

package/README.md

@@ -100,10 +100,11 @@ Use `agent-runtimes` for runtime workloads (`RuntimeClient`, `@datalayer`, snaps
 
 ## Examples
 
-Examples have moved to Agent Runtimes:
+The [examples](./examples/README.md) show the Datalayer Client at work:
 
-- [Agent Runtimes examples README](https://github.com/datalayer/agent-runtimes/blob/main/examples/README.md)
-- [Agent Runtimes examples directory](https://github.com/datalayer/agent-runtimes/tree/main/examples)
+- [OpenTelemetry observability](./examples/otel/README.md): instrument Datalayer usage with OpenTelemetry traces and metrics, with a small FastAPI service and a React UI to visualize them (`make` targets in [examples/otel](./examples/otel)).
+
+For agents, chats and sandboxes built on the client, see the [Agent Runtimes examples](https://github.com/datalayer/agent-runtimes/tree/main/examples).
 
 ## Platform Integration
 

package/lib/components/buttons/CopyToClipboardButton.d.ts

@@ -0,0 +1,13 @@
+export type CopyToClipboardButtonProps = {
+    value: string;
+    ariaLabel?: string;
+    successText?: string;
+    errorText?: string;
+    direction?: 'n' | 's' | 'e' | 'w' | 'nw' | 'ne' | 'sw' | 'se';
+    disabled?: boolean;
+    size?: 'small' | 'medium';
+    variant?: 'default' | 'invisible' | 'primary' | 'danger';
+    onResult?: (copied: boolean) => void;
+};
+export declare function CopyToClipboardButton({ value, ariaLabel, successText, errorText, direction, disabled, size, variant, onResult, }: CopyToClipboardButtonProps): import("react").JSX.Element;
+export default CopyToClipboardButton;

package/lib/components/buttons/CopyToClipboardButton.js

@@ -0,0 +1,73 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * A button that copies a value, its tooltip saying what it copies, then
+ * whether it did.
+ *
+ * @module components/buttons/CopyToClipboardButton
+ */
+import { useMemo, useState } from 'react';
+import { IconButton, Tooltip } from '@primer/react';
+import { CopyIcon } from '@primer/octicons-react';
+const ellipsize = (value, max = 96) => {
+    if (!value) {
+        return '';
+    }
+    if (value.length <= max) {
+        return value;
+    }
+    const head = Math.floor((max - 1) / 2);
+    const tail = max - head - 1;
+    return `${value.slice(0, head)}…${value.slice(-tail)}`;
+};
+export function CopyToClipboardButton({ value, ariaLabel = 'Copy to clipboard', successText = 'Copied', errorText = 'Unable to copy', direction = 'n', disabled = false, size = 'small', variant = 'invisible', onResult, }) {
+    const [status, setStatus] = useState('idle');
+    const hasValue = Boolean(value && value.trim());
+    const tooltip = useMemo(() => {
+        if (status === 'success') {
+            return successText;
+        }
+        if (status === 'error') {
+            return errorText;
+        }
+        return hasValue ? `Copy: ${ellipsize(value)}` : 'Nothing to copy';
+    }, [status, successText, errorText, hasValue, value]);
+    const handleClick = async () => {
+        if (!hasValue || disabled) {
+            return;
+        }
+        try {
+            if (!navigator?.clipboard?.writeText) {
+                throw new Error('Clipboard API unavailable');
+            }
+            await navigator.clipboard.writeText(value);
+            setStatus('success');
+            onResult?.(true);
+            window.setTimeout(() => setStatus('idle'), 1500);
+        }
+        catch {
+            setStatus('error');
+            onResult?.(false);
+            window.setTimeout(() => setStatus('idle'), 1800);
+        }
+    };
+    const isDisabled = disabled || !hasValue;
+    const button = (_jsx(IconButton, { "aria-label": ariaLabel, icon: CopyIcon, size: size, variant: variant, disabled: isDisabled, onClick: handleClick }));
+    /*
+     * A disabled button wears no tooltip.
+     *
+     * `Tooltip` only takes interactive content — `button:not([disabled])` — and
+     * throws on anything else, which is what a disabled button is. Nothing is
+     * lost by leaving it out: a disabled element fires no pointer event, so the
+     * tooltip would never have shown. `IconButton` does the same with the one
+     * it renders of its own.
+     */
+    if (isDisabled) {
+        return button;
+    }
+    return (_jsx(Tooltip, { text: tooltip, direction: direction, children: button }));
+}
+export default CopyToClipboardButton;

package/lib/components/buttons/index.d.ts

@@ -1,3 +1,4 @@
+export * from './CopyToClipboardButton';
 export * from './DownloadCSVButton';
 export * from './DownloadJsonButton';
 export * from './LongActionButton';

package/lib/components/buttons/index.js

@@ -2,6 +2,7 @@
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
+export * from './CopyToClipboardButton.js';
 export * from './DownloadCSVButton.js';
 export * from './DownloadJsonButton.js';
 export * from './LongActionButton.js';

package/lib/hooks/deckSpec.d.ts

@@ -0,0 +1,2 @@
+/** The value a deck's `model_s` holds, or `undefined` when it holds none. */
+export declare const parseDeckSpec: (text: unknown) => unknown;

package/lib/hooks/deckSpec.js

@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * A deck's specification, as Spacer serves it: YAML.
+ *
+ * `GET /decks/{id}` inlines the specification as `model_s`, the text Spacer
+ * stored — YAML, or JSON for a deck stored before the specification was
+ * YAML, which the same parser reads (JSON is YAML). Saving sends the parsed
+ * value back (`PUT /decks/{id}/model`), and Spacer writes it as YAML.
+ *
+ * @module hooks/deckSpec
+ */
+import { parse } from 'yaml';
+/** The value a deck's `model_s` holds, or `undefined` when it holds none. */
+export const parseDeckSpec = (text) => {
+    if (typeof text !== 'string' || !text.trim()) {
+        return undefined;
+    }
+    return parse(text);
+};

package/lib/hooks/useCache.d.ts

@@ -38,6 +38,27 @@ type IAnySpace = any;
 export type CacheProps = {
     loginRoute?: string;
 };
+/** A deck's video, as Spacer keeps it with the deck (`GET /decks/{id}/video`). */
+export type SavedDeckVideo = {
+    /** Signed: plays it for `expiresIn` seconds. */
+    url: string;
+    /** Signed: downloads it as `<deck name>.mp4`. */
+    downloadUrl: string;
+    /** Signed: its first frame, a PNG. */
+    posterUrl: string;
+    /** Its captions, as WebVTT text. */
+    captions: string;
+    width: number;
+    height: number;
+    bytes: number;
+    madeAt: string;
+    madeBy: string;
+    /** When the deck was last edited, if it says. */
+    editedAt: string;
+    /** The deck has been edited since the video was made. */
+    stale: boolean;
+    expiresIn: number;
+};
 export type ISearchOpts = {
     q: string;
     types: string[];
@@ -282,6 +303,8 @@ export declare const queryKeys: {
         readonly detail: (id: string) => readonly ["decks", "detail", string];
         readonly bySpace: (spaceId: string) => readonly ["decks", "space", string];
         readonly model: (deckId: string) => readonly ["decks", "detail", string, "model"];
+        /** Under the detail: saving the deck refreshes whether it is stale. */
+        readonly video: (deckId: string) => readonly ["decks", "detail", string, "video"];
     };
     readonly cells: {
         readonly all: () => readonly ["cells"];
@@ -803,6 +826,15 @@ export declare const useCache: ({ loginRoute }?: CacheProps) => {
         spec: unknown;
     }, unknown>;
     useCloneDeck: () => import("@tanstack/react-query").UseMutationResult<any, Error, string, unknown>;
+    useSavedDeckVideo: (deckId: string) => import("@tanstack/react-query").UseQueryResult<SavedDeckVideo | null, Error>;
+    useSaveDeckVideo: () => import("@tanstack/react-query").UseMutationResult<SavedDeckVideo, Error, {
+        deckId: string;
+        video: Blob;
+        captions: string;
+        poster: Blob;
+        spec: unknown;
+    }, unknown>;
+    useDeleteDeckVideo: () => import("@tanstack/react-query").UseMutationResult<any, Error, string, unknown>;
     useDocument: (documentId: string) => import("@tanstack/react-query").UseQueryResult<any, Error>;
     useDocumentsBySpace: (spaceId: string) => import("@tanstack/react-query").UseQueryResult<any, Error>;
     useCreateDocument: () => import("@tanstack/react-query").UseMutationResult<any, Error, {
@@ -958,6 +990,12 @@ export declare const useCache: ({ loginRoute }?: CacheProps) => {
         data?: string;
     }, unknown>;
     useResetItemImage: () => import("@tanstack/react-query").UseMutationResult<any, Error, string, unknown>;
+    useSetItemVideo: () => import("@tanstack/react-query").UseMutationResult<any, Error, {
+        itemId: string;
+        video: Blob;
+        captions: string;
+        poster: Blob;
+    }, unknown>;
     useCountItemReuse: () => import("@tanstack/react-query").UseMutationResult<any, Error, {
         itemId: string;
         kind: "clone" | "instantiate";
@@ -975,6 +1013,14 @@ export declare const useCache: ({ loginRoute }?: CacheProps) => {
             ref?: string;
             data?: string;
         };
+        /**
+         * Publish a deck *as a video*: the video saved with it in its space
+         * becomes the published deck's video — its page plays it and its
+         * shared link announces it (`og:video`). The library copies it in
+         * the same request that publishes, and refuses before publishing a
+         * deck that has none.
+         */
+        video?: boolean;
         /**
          * The publisher's own words for their work, which is what somebody
          * else will search for.
@@ -1415,6 +1461,8 @@ export declare const useCache: ({ loginRoute }?: CacheProps) => {
             readonly detail: (id: string) => readonly ["decks", "detail", string];
             readonly bySpace: (spaceId: string) => readonly ["decks", "space", string];
             readonly model: (deckId: string) => readonly ["decks", "detail", string, "model"];
+            /** Under the detail: saving the deck refreshes whether it is stale. */
+            readonly video: (deckId: string) => readonly ["decks", "detail", string, "video"];
         };
         readonly cells: {
             readonly all: () => readonly ["cells"];

package/lib/hooks/useCache.js

@@ -39,6 +39,7 @@
 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 { asSpace } from './cacheConverters.js';
+import { parseDeckSpec } from './deckSpec.js';
 import { libraryAppFieldsOf } from './libraryApp.js';
 import { unlinkIAMProvider } from './unlinkIAMProvider.js';
 import { useCoreStore, useIAMStore, profileStore } from '../state/index.js';
@@ -368,6 +369,8 @@ export const queryKeys = {
         detail: (id) => [...queryKeys.decks.details(), id],
         bySpace: (spaceId) => [...queryKeys.decks.all(), 'space', spaceId],
         model: (deckId) => [...queryKeys.decks.detail(deckId), 'model'],
+        /** Under the detail: saving the deck refreshes whether it is stale. */
+        video: (deckId) => [...queryKeys.decks.detail(deckId), 'video'],
     },
     // Cells
     cells: {
@@ -721,6 +724,10 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             meta.publisher = raw.publisher;
         if (raw.image !== undefined)
             meta.image = raw.image;
+        // A deck's video, made by its owner: `url`, `captionsUrl`, `posterUrl`,
+        // `width`, `height`. Absent when it has none.
+        if (raw.video)
+            meta.video = raw.video;
         /*
          * Where the artifact can be opened for editing.
          *
@@ -1074,7 +1081,8 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             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,
+            // YAML, as Spacer stores it (a deck stored as JSON reads the same).
+            spec: parseDeckSpec(raw.model_s),
             public: raw.is_public_b ?? false,
             creationDate: new Date(raw.creation_ts_dt),
             lastUpdateDate: raw.last_update_ts_dt
@@ -2628,6 +2636,77 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             },
         });
     };
+    /**
+     * The video saved with a deck in its space, or `null` when it has none.
+     *
+     * Signed URLs that read it for a few hours (`url`, `posterUrl`, and
+     * `downloadUrl`, an attachment named after the deck), its captions inline
+     * (WebVTT), its size, when it was made, and `stale` — the deck has been
+     * edited since: its spec is not the one the video was made from.
+     */
+    const useSavedDeckVideo = (deckId) => {
+        return useQuery({
+            queryKey: queryKeys.decks.video(deckId),
+            queryFn: async () => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.spacerUrl}/api/spacer/v1/decks/${encodeURIComponent(deckId)}/video`,
+                    method: 'GET',
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to read the deck video');
+                }
+                return (resp.video ?? null);
+            },
+            ...DEFAULT_QUERY_OPTIONS,
+            enabled: !!deckId,
+        });
+    };
+    /**
+     * Keep the video the deck engine made of a deck with the deck, in its
+     * space, replacing the one it had: the MP4, its WebVTT captions, its
+     * poster, and the spec it was made from.
+     */
+    const useSaveDeckVideo = () => {
+        return useMutation({
+            mutationFn: async ({ deckId, video, captions, poster, spec, }) => {
+                const body = new FormData();
+                body.append('video', video, 'video.mp4');
+                body.append('captions', new Blob([captions], { type: 'text/vtt' }), 'captions.vtt');
+                body.append('poster', poster, 'poster.png');
+                body.append('spec', JSON.stringify(spec));
+                const resp = await requestDatalayer({
+                    url: `${configuration.spacerUrl}/api/spacer/v1/decks/${encodeURIComponent(deckId)}/video`,
+                    method: 'PUT',
+                    body,
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to save the video');
+                }
+                return resp.video;
+            },
+            onSuccess: (video, { deckId }) => {
+                queryClient.setQueryData(queryKeys.decks.video(deckId), video);
+            },
+        });
+    };
+    /** The deck without its saved video. */
+    const useDeleteDeckVideo = () => {
+        return useMutation({
+            mutationFn: async (deckId) => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.spacerUrl}/api/spacer/v1/decks/${encodeURIComponent(deckId)}/video`,
+                    method: 'DELETE',
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to remove the video');
+                }
+                return resp;
+            },
+            onSuccess: (_, deckId) => {
+                queryClient.setQueryData(queryKeys.decks.video(deckId), null);
+            },
+        });
+    };
     /**
      * Clone notebook
      */
@@ -6915,6 +6994,31 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             onSuccess: invalidateArtifactVisibility,
         });
     };
+    /**
+     * A published deck's video, made in its owner's browser by the deck
+     * engine: the MP4, its WebVTT captions and its poster (the first slide).
+     * Making it again replaces it.
+     */
+    const useSetItemVideo = () => {
+        return useMutation({
+            mutationFn: async ({ itemId, video, captions, poster, }) => {
+                const body = new FormData();
+                body.append('video', video, 'video.mp4');
+                body.append('captions', new Blob([captions], { type: 'text/vtt' }), 'captions.vtt');
+                body.append('poster', poster, 'poster.png');
+                const resp = await requestDatalayer({
+                    url: `${configuration.libraryUrl}/api/library/v1/items/${encodeURIComponent(itemId)}/video`,
+                    method: 'PUT',
+                    body,
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'Failed to set the video');
+                }
+                return resp.video;
+            },
+            onSuccess: invalidateArtifactVisibility,
+        });
+    };
     /** Publish a public artifact natively to LinkedIn through Library's saga. */
     const usePublishLinkedInShare = () => {
         return useMutation({
@@ -7131,7 +7235,7 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
     const usePublishArtifact = () => {
         const setImage = useSetItemImage();
         return useMutation({
-            mutationFn: async ({ itemId, image, tags, description, }) => {
+            mutationFn: async ({ itemId, image, tags, description, video, }) => {
                 /*
                  * Publish first, then dress it.
                  *
@@ -7156,6 +7260,7 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                         // words must not be able to clear them by omission.
                         ...(tags === undefined ? {} : { tags }),
                         ...(description === undefined ? {} : { description }),
+                        ...(video ? { video: true } : {}),
                     },
                 });
                 if (!resp.success) {
@@ -8584,6 +8689,9 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
         useUpdateDeck,
         useUpdateDeckModel,
         useCloneDeck,
+        useSavedDeckVideo,
+        useSaveDeckVideo,
+        useDeleteDeckVideo,
         // Documents
         useDocument,
         useDocumentsBySpace,
@@ -8655,6 +8763,7 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
         useSetFeaturedRank,
         useSetItemImage,
         useResetItemImage,
+        useSetItemVideo,
         useCountItemReuse,
         useSyncArtifactCatalogue,
         usePublishArtifact,

package/lib/state/substates/NavigationState.js

@@ -301,8 +301,22 @@ export function viewForRoute(route, current) {
     if (path === '/apps' || path.startsWith('/apps/')) {
         return 'apps';
     }
+    // A space's decks and teaching pages are drawn beside the Agentify sidebar:
+    // filed under the Platform, the Platform button came back to a deck with
+    // the Agentify sidebar beside it (reported 23 October 2026).
+    if (AGENTIFY_SPACE_PAGE.test(path) || AGENTIFY_ACCOUNT_PAGE.test(path)) {
+        return 'agentify';
+    }
     return 'home';
 }
+/**
+ * `/<account>/<space>/<kind>[/…]` for the kinds a space shows beside the
+ * Agentify sidebar — decks, courses and what a course is made of. The
+ * documentation (`/docs/…`) is never an account.
+ */
+const AGENTIFY_SPACE_PAGE = /^\/(?!docs\/)[^/]+\/[^/]+\/(?:decks|courses|course|lessons|exercises|assignments)(?:\/|$)/;
+/** `/<account>/courses`: an account's courses, beside the Agentify sidebar. */
+const AGENTIFY_ACCOUNT_PAGE = /^\/(?!docs\/)[^/]+\/courses$/;
 /** Whether a page may be the one a shell returns to. */
 function isRouteOfView(route, view) {
     return (typeof route === 'string' &&

package/lib/views/profile/UserIdentity.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Who an account is, to be read: its avatar, then its username, display
+ * name, initials, origin and identifier, the identifier with a button that
+ * copies it.
+ *
+ * It is given the identity and fetches nothing, so any host draws it from
+ * what it already holds: the web's profile page beside its form, VS Code's
+ * Profile view from its signed-in user.
+ *
+ * @module views/profile/UserIdentity
+ */
+import type { JSX } from 'react';
+/** What {@link UserIdentity} shows of an account. */
+export interface UserIdentityProfile {
+    /** The account's identifier. */
+    id?: string;
+    username: string;
+    display_name: string;
+    initials: string;
+    /** Its photograph, when it has one. */
+    avatar_url?: string;
+    /** Its chosen picture, which wins over the photograph. */
+    avatar_icon?: string;
+    /** Where the account comes from (the identity provider). */
+    origin?: string;
+}
+export interface UserIdentityProps {
+    identity: UserIdentityProfile;
+    /** Whether the identifier is shown. @default true */
+    displayId?: boolean;
+    /**
+     * Whether the display name and the initials are shown. They are computed
+     * from the first and the last name, so a host showing the form that edits
+     * those states them there instead. @default true
+     */
+    displayComputed?: boolean;
+    /** Rendered under the avatar, typically the button changing it. */
+    avatarAction?: JSX.Element;
+}
+export declare const UserIdentity: ({ identity, displayId, displayComputed, avatarAction, }: UserIdentityProps) => JSX.Element;
+export default UserIdentity;

package/lib/views/profile/UserIdentity.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Text } from '@primer/react';
+import { Box } from '@datalayer/primer-addons';
+import { UserAvatar } from '../../components/avatars/index.js';
+import { CopyToClipboardButton } from '../../components/buttons/index.js';
+/** One row of the list: its label, then its value. */
+const Row = ({ label, children, }) => (_jsxs(_Fragment, { children: [_jsx(Box, { p: 1, children: _jsx(Text, { style: { fontWeight: 'bold' }, children: label }) }), _jsx(Box, { p: 1, display: "flex", alignItems: "center", gap: 1, children: typeof children === 'string' ? _jsx(Text, { children: children }) : children })] }));
+export const UserIdentity = ({ identity, displayId = true, displayComputed = true, avatarAction, }) => (_jsxs(Box, { children: [_jsxs(Box, { display: "flex", flexDirection: "column", alignItems: "flex-start", gap: 2, children: [_jsx(UserAvatar, { avatarUrl: identity.avatar_url, avatar: identity.avatar_icon, size: 100 }), avatarAction] }), _jsxs(Box, { display: "grid", gridTemplateColumns: "1fr 2fr", rowGap: 3, columnGap: 3, maxWidth: 500, mt: 3, children: [_jsx(Row, { label: "Username", children: identity.username }), displayComputed && (_jsxs(_Fragment, { children: [_jsx(Row, { label: "Display name", children: identity.display_name }), _jsx(Row, { label: "Initials", children: identity.initials })] })), identity.origin && _jsx(Row, { label: "Origin", children: identity.origin }), displayId && identity.id && (_jsx(Row, { label: "UID", children: _jsxs(_Fragment, { children: [_jsx(Text, { children: identity.id }), _jsx(CopyToClipboardButton, { value: identity.id, ariaLabel: "Copy the identifier of the account" })] }) }))] })] }));
+export default UserIdentity;

package/lib/views/profile/index.d.ts

@@ -1,2 +1,4 @@
 export { UserBadge } from './UserBadge';
 export type { UserBadgeProps } from './UserBadge';
+export { UserIdentity } from './UserIdentity';
+export type { UserIdentityProfile, UserIdentityProps } from './UserIdentity';

package/lib/views/profile/index.js

@@ -3,3 +3,4 @@
  * Distributed under the terms of the Modified BSD License.
  */
 export { UserBadge } from './UserBadge.js';
+export { UserIdentity } from './UserIdentity.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/core",
-    "version": "1.2.23",
+    "version": "1.2.24",
     "type": "module",
     "workspaces": [
         ".",
@@ -177,6 +177,7 @@
         "usehooks-ts": "3.1.1",
         "uuid": "^13.0.0",
         "validator": "^13.7.0",
+        "yaml": "^2.9.1",
         "zod": "^4.1.13",
         "zod-to-json-schema": "^3.25.0",
         "zustand": "^4.4.1"