@datalayer/core 1.2.14 → 1.2.15

package/lib/hooks/index.d.ts

@@ -2,6 +2,7 @@ export * from './useAuthorization';
 export * from './useBackdrop';
 export * from './useBackdropJupyterLab';
 export * from './useCache';
+export * from './libraryApp';
 export * from './useContainsFocus';
 export * from './useContents';
 export * from './useDatalayer';

package/lib/hooks/index.js

@@ -6,6 +6,7 @@ export * from './useAuthorization.js';
 export * from './useBackdrop.js';
 export * from './useBackdropJupyterLab.js';
 export * from './useCache.js';
+export * from './libraryApp.js';
 export * from './useContainsFocus.js';
 export * from './useContents.js';
 export * from './useDatalayer.js';

package/lib/hooks/libraryApp.d.ts

@@ -0,0 +1,37 @@
+/**
+ * What the Library says of a published application beyond any item's fields:
+ * its face, its kind and whether it runs live.
+ *
+ * Spacer keeps them beside the app's item, from its Appspec, and the Library
+ * projection carries them: `face_s` (the JSON of its `id`, `emoji`, `avatar`
+ * and `banner`, each only when set), `app_kind_s` and `runs_live_b` — an app
+ * that runs live can be tried before it is cloned: not a decision, and naming
+ * the agent it runs on.
+ *
+ * @module hooks/libraryApp
+ */
+/** The kinds of application. */
+export declare const LIBRARY_APP_KINDS: readonly ["decision", "chat", "widget", "worker"];
+export type LibraryAppKind = (typeof LIBRARY_APP_KINDS)[number];
+/** An application's face, as its Appspec says it: each only when set. */
+export type LibraryAppFace = {
+    /** The Appspec's id: what seeds its banner, and the agent it runs as. */
+    id?: string;
+    emoji?: string;
+    /** The drawing chosen, by name, from the profile's set. */
+    avatar?: string;
+    /** The banner chosen, by name, from the profile's set. */
+    banner?: string;
+};
+export type LibraryAppFields = {
+    /** None when the Library answered without one. */
+    face?: LibraryAppFace;
+    /** None when the Library answered without one. */
+    appKind?: LibraryAppKind;
+    /** Whether it can be tried before it is cloned. */
+    runsLive: boolean;
+};
+/** The face `face_s` carries; a value that is not a face's JSON is refused. */
+export declare function libraryAppFaceOf(value: unknown): LibraryAppFace | undefined;
+/** The face, kind and liveness of an app as the Library answers it. */
+export declare function libraryAppFieldsOf(raw: Record<string, unknown>): LibraryAppFields;

package/lib/hooks/libraryApp.js

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * What the Library says of a published application beyond any item's fields:
+ * its face, its kind and whether it runs live.
+ *
+ * Spacer keeps them beside the app's item, from its Appspec, and the Library
+ * projection carries them: `face_s` (the JSON of its `id`, `emoji`, `avatar`
+ * and `banner`, each only when set), `app_kind_s` and `runs_live_b` — an app
+ * that runs live can be tried before it is cloned: not a decision, and naming
+ * the agent it runs on.
+ *
+ * @module hooks/libraryApp
+ */
+/** The kinds of application. */
+export const LIBRARY_APP_KINDS = [
+    'decision',
+    'chat',
+    'widget',
+    'worker',
+];
+const FACE_KEYS = ['id', 'emoji', 'avatar', 'banner'];
+/** The face `face_s` carries; a value that is not a face's JSON is refused. */
+export function libraryAppFaceOf(value) {
+    if (value === undefined || value === null || value === '') {
+        return undefined;
+    }
+    if (typeof value !== 'string') {
+        throw new Error(`An app's face is not a string: ${String(value)}`);
+    }
+    const parsed = JSON.parse(value);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`An app's face is not an object: ${value}`);
+    }
+    const face = {};
+    for (const key of FACE_KEYS) {
+        const field = parsed[key];
+        if (typeof field === 'string' && field) {
+            face[key] = field;
+        }
+    }
+    return face;
+}
+/** The face, kind and liveness of an app as the Library answers it. */
+export function libraryAppFieldsOf(raw) {
+    const kind = raw.app_kind_s;
+    if (kind !== undefined &&
+        !LIBRARY_APP_KINDS.includes(kind)) {
+        throw new Error(`An app's kind is not one of ${LIBRARY_APP_KINDS}: ${String(kind)}`);
+    }
+    const face = libraryAppFaceOf(raw.face_s);
+    return {
+        ...(face ? { face } : {}),
+        ...(kind ? { appKind: kind } : {}),
+        runsLive: raw.runs_live_b === true,
+    };
+}

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 { libraryAppFieldsOf } from './libraryApp.js';
 import { useCoreStore, useIAMStore, profileStore } from '../state/index.js';
 import { asDisplayName, namesAsInitials, asArray } from '../utils/index.js';
 import { useDatalayer } from './useDatalayer.js';
@@ -880,10 +881,13 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
     /**
      * A published agentic UI application: what it answers, and its definition
      * as the library hands it over — `model_s`, the string the Studio reads
-     * the definition from, left unparsed because the Studio owns its shape.
+     * the definition from, left unparsed because the Studio owns its shape —
+     * and its face, its kind and whether it runs live (`libraryAppFieldsOf`),
+     * so its card draws it and the gallery opens one that runs live.
      */
     const toApp = (raw) => {
         return {
+            ...libraryAppFieldsOf(raw),
             id: raw.uid,
             type: 'app',
             name: raw.name_t,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/core",
-    "version": "1.2.14",
+    "version": "1.2.15",
     "type": "module",
     "workspaces": [
         ".",