@datalayer/core 1.2.12 → 1.2.14

package/lib/state/substates/NavigationState.js

@@ -33,9 +33,14 @@ import { createStore } from 'zustand/vanilla';
 import { registerSessionState } from '../sessionEnd.js';
 /** The shells, and where each one opens when it has not been visited. */
 export const NAVIGATION_VIEW_HOMES = {
-    home: '/',
+    studio: '/studio',
+    // Not `/`: the root is the Studio's, so the Power shell has an address of
+    // its own to be sent to.
+    home: '/power',
     agentify: '/agentify',
     admin: '/admin',
+    // The applications: what a builder opens LOOP for.
+    loop: '/loop/apps',
 };
 /** Well-known view identifiers for {@link NavigationState.tabsByView}. */
 export const LIBRARY_VIEW = 'library';
@@ -50,7 +55,11 @@ const SHELL_COOKIE = 'datalayer-signed-in-view';
 const FORMER_TABS_KEY = 'datalayer_view_tabs';
 /** Days a remembered shell lives in the cookie. */
 const COOKIE_MAX_AGE_DAYS = 365;
-const isView = (value) => value === 'home' || value === 'agentify' || value === 'admin';
+const isView = (value) => value === 'studio' ||
+    value === 'home' ||
+    value === 'agentify' ||
+    value === 'admin' ||
+    value === 'loop';
 function readCookie(name) {
     if (typeof document === 'undefined') {
         return undefined;
@@ -90,7 +99,8 @@ function restore() {
             const parsed = JSON.parse(stored);
             // The landing kept this under the same key through zustand's
             // `persist`, which wraps what it writes in `{ state, version }`.
-            persisted = parsed?.state ?? parsed ?? {};
+            const kept = parsed?.state ?? parsed;
+            persisted = kept && typeof kept === 'object' ? kept : {};
         }
         catch {
             persisted = {};
@@ -112,8 +122,32 @@ function restore() {
     if (isView(shell)) {
         persisted.view = shell;
     }
+    persisted.lastRouteByView = restoredRoutes(persisted.lastRouteByView);
     return persisted;
 }
+/**
+ * The shells' pages as they were written down, less the ones no shell
+ * returns to.
+ *
+ * What is in storage was written by whichever version ran last, under that
+ * version's rules. Before the Power shell had an address of its own, its
+ * page could be the root — which is now the Studio's, and would send Power
+ * to the Studio — and an earlier version filed pages under the shell the
+ * toggle named. Such a page is dropped here rather than carried, so the next
+ * write does not put it back.
+ */
+function restoredRoutes(stored) {
+    const routes = {};
+    if (!stored || typeof stored !== 'object') {
+        return routes;
+    }
+    for (const [view, route] of Object.entries(stored)) {
+        if (isView(view) && isRouteOfView(route, view)) {
+            routes[view] = route;
+        }
+    }
+    return routes;
+}
 function persist(state) {
     const written = {
         view: state.view,
@@ -128,6 +162,18 @@ function persist(state) {
     }
     writeCookie(SHELL_COOKIE, state.view);
 }
+/**
+ * The path of a route: what is before its query and its fragment.
+ *
+ * A route is what the reader was at — `/settings/profile?tab=keys#tokens` —
+ * and the shell it belongs to is decided by its path alone. Cutting only at
+ * `?` left a fragment attached, so `/settings#profile` was not `/settings`:
+ * it read as a shell's own page and moved the shell.
+ */
+function pathOf(route) {
+    const end = route.search(/[?#]/);
+    return end === -1 ? route : route.slice(0, end);
+}
 /**
  * Whether a page is worth remembering as a shell's.
  *
@@ -139,17 +185,30 @@ export function isRememberableRoute(route) {
     if (!route.startsWith('/')) {
         return false;
     }
-    const path = route.split('?')[0];
-    return ![
+    const path = pathOf(route);
+    return (![
         '/signin',
         '/signup',
         '/login',
         '/logout',
         '/oauth2',
         '/oauth',
-        '/docs',
         '/join',
-    ].some(prefix => path === prefix || path.startsWith(`${prefix}/`));
+    ].some(prefix => path === prefix || path.startsWith(`${prefix}/`)) &&
+        !isShellNeutralRoute(route));
+}
+/**
+ * Whether a page belongs to no shell: the settings, the documentation and
+ * the decks.
+ *
+ * They are read from whichever shell the reader is in — its sidebar stays
+ * beside them and the header's selector does not move — so they are never a
+ * shell's own page: opening one does not change the shell, and no shell
+ * returns to one.
+ */
+export function isShellNeutralRoute(route) {
+    const path = pathOf(route);
+    return ['/settings', '/docs', '/decks'].some(prefix => path === prefix || path.startsWith(`${prefix}/`));
 }
 /**
  * The shell a route belongs to, read off its first segment.
@@ -159,20 +218,51 @@ export function isRememberableRoute(route) {
  * reached Home through a sidebar link while the toggle still said Agentify
  * had their Home pages filed under Agentify — and the toggle, seeing
  * "Agentify" already chosen, did nothing when they clicked it.
+ *
+ * A shell-neutral page (the settings, the documentation) has no shell of its
+ * own: given the shell the reader is in (`current`), that is the answer, so
+ * the sidebar and the header stay where they were. Without it the settings
+ * read as the Studio's and the documentation as Power's, as they once were.
  */
-export function viewForRoute(route) {
-    const path = route.split('?')[0];
+export function viewForRoute(route, current) {
+    const path = pathOf(route);
+    if (current && isShellNeutralRoute(route)) {
+        return current;
+    }
+    // The root is the Studio: what a signed-in reader opens on. The settings
+    // are read from it too, with its sidebar beside them — and so is the
+    // agentspecs catalogue, the specs an app is composed from.
+    if (path === '/' ||
+        path === '/studio' ||
+        path.startsWith('/studio/') ||
+        path === '/settings' ||
+        path.startsWith('/settings/') ||
+        path === '/agentspecs' ||
+        path.startsWith('/agentspecs/')) {
+        return 'studio';
+    }
     if (path === '/agentify' || path.startsWith('/agentify/')) {
         return 'agentify';
     }
     if (path === '/admin' || path.startsWith('/admin/')) {
         return 'admin';
     }
+    if (path === '/loop' || path.startsWith('/loop/')) {
+        return 'loop';
+    }
     return 'home';
 }
+/** Whether a page may be the one a shell returns to. */
+function isRouteOfView(route, view) {
+    return (typeof route === 'string' &&
+        isRememberableRoute(route) &&
+        viewForRoute(route) === view);
+}
 const initial = restore();
 export const navigationStore = createStore((set, get) => ({
-    view: initial.view ?? 'home',
+    // The Studio, for a reader who never chose: a cookie from before it
+    // existed says `home`, and is honoured.
+    view: initial.view ?? 'studio',
     lastRouteByView: initial.lastRouteByView ?? {},
     tabsByView: initial.tabsByView ?? {},
     requestedRoute: undefined,
@@ -210,9 +300,10 @@ export const navigationStore = createStore((set, get) => ({
         // Only a page of that shell: an earlier version filed pages under the
         // shell the toggle named rather than the one the route belonged to, so a
         // reader can still have `/items` written down as Agentify's page. Going
-        // "to Agentify" must never land on a Home page.
+        // "to Agentify" must never land on a Home page — nor Power on the root,
+        // which was its page before it had `/power` and is now the Studio's.
         const remembered = get().lastRouteByView[view];
-        return remembered && viewForRoute(remembered) === view
+        return isRouteOfView(remembered, view)
             ? remembered
             : NAVIGATION_VIEW_HOMES[view];
     },

package/lib/utils/Handles.js

@@ -2,7 +2,7 @@
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-const EXT_URN_PREFIX = 'urn:dla:iam:ext::';
+import { IAM_PROVIDER_URN_PREFIX as EXT_URN_PREFIX } from '../models/URN.js';
 export function isExternalUrnHandle(handle) {
     const normalized = (handle || '').trim().toLowerCase();
     return normalized.startsWith(EXT_URN_PREFIX);

package/lib/views/mcp/McpDashboard.js

@@ -3,7 +3,7 @@ import { useMemo, useRef, useState } from 'react';
 import { ActionList, ActionMenu, Button, Heading, Label, Link, RelativeTime, Select, Spinner, Text, } from '@primer/react';
 import { Blankslate, DataTable, Dialog, Table, } from '@primer/react/experimental';
 import { Box } from '@datalayer/primer-addons';
-import { ChecklistIcon, KebabHorizontalIcon, PlayIcon, PlugIcon, StackIcon, TelescopeIcon, } from '@primer/octicons-react';
+import { ChecklistIcon, KebabHorizontalIcon, PlayIcon, PlugIcon, StackIcon, } from '@primer/octicons-react';
 import { ShareAccessDialog, sandboxSharingUrl } from '../../components/sharing/index.js';
 import { ClientBadge, McpErrorBlankslate } from '../../components/mcp/index.js';
 import { useDisconnectAgent, useMcpActivity, useTerminateBinding, } from '../../hooks/useMcp.js';
@@ -54,7 +54,7 @@ const boundTo = (client) => {
     return '';
 };
 const countLook = (tone) => tone === 'danger' ? 'danger.fg' : 'fg.default';
-const Count = ({ label, value, tone = 'neutral', note, }) => (_jsxs(Box, { sx: {
+const Count = ({ label, value, tone = 'neutral', note, to, onOpen, }) => (_jsxs(Box, { sx: {
         p: 3,
         border: '1px solid',
         borderColor: 'border.default',
@@ -66,7 +66,14 @@ const Count = ({ label, value, tone = 'neutral', note, }) => (_jsxs(Box, { sx: {
                 fontSize: 4,
                 fontWeight: 'bold',
                 color: countLook(tone),
-            }, children: value }), _jsx(Text, { sx: { display: 'block', fontSize: 0, color: 'fg.muted' }, children: label }), note && (_jsx(Text, { sx: { display: 'block', fontSize: 0, color: 'fg.subtle', mt: 1 }, children: note }))] }));
+            }, children: value }), to ? (_jsx(Link, { href: to, onClick: (event) => {
+                // A modified click asks for a new tab; `href` is real, so let it.
+                if (event.metaKey || event.ctrlKey || event.shiftKey) {
+                    return;
+                }
+                event.preventDefault();
+                onOpen?.(to);
+            }, sx: { display: 'block', fontSize: 0 }, children: label })) : (_jsx(Text, { sx: { display: 'block', fontSize: 0, color: 'fg.muted' }, children: label })), note && (_jsx(Text, { sx: { display: 'block', fontSize: 0, color: 'fg.subtle', mt: 1 }, children: note }))] }));
 /** A panel that has nothing to show, and the step that would fill it. */
 const PanelEmpty = ({ icon: Icon, heading, description, action, }) => (_jsxs(Blankslate, { border: true, spacious: true, children: [_jsx(Blankslate.Visual, { children: _jsx(Icon, { size: "medium" }) }), _jsx(Blankslate.Heading, { children: heading }), _jsx(Blankslate.Description, { children: _jsx(Text, { as: "p", sx: { textAlign: 'center', m: 0 }, children: description }) }), action && (_jsx(Button, { size: "small", onClick: action.onClick, children: action.label }))] }));
 export const McpDashboard = ({ errorState, routes, org, showTitle = true, section, }) => {
@@ -379,7 +386,10 @@ export const McpDashboard = ({ errorState, routes, org, showTitle = true, sectio
                             'repeat(3, 1fr)',
                             'repeat(6, 1fr)',
                         ],
-                    }, children: [_jsx(Count, { label: "Clients connected", value: clients.length }), _jsx(Count, { label: "Sandboxes bound", value: sandboxes.filter(binding => (binding.state ?? 'active') === 'active').length }), _jsx(Count, { label: "Tasks running", value: data?.tasks.length ?? 0 }), _jsx(Count, { label: "Calls today", value: data?.today.calls ?? 0 }), _jsx(Count, { label: "Refusals today", value: data?.today.refusals ?? 0, tone: (data?.today.refusals ?? 0) > 0 ? 'danger' : 'neutral' }), _jsx(Count, { label: "Credits by agents", value: data?.today.credits ?? 0, note: "today" })] }))), draws('agents') &&
+                    }, children: [_jsx(Count, { label: "Clients connected", value: clients.length, to: routes.agents, onOpen: navigate }), _jsx(Count, { label: "Sandboxes bound", to: routes.sandboxes, onOpen: navigate, value: sandboxes.filter(binding => (binding.state ?? 'active') === 'active').length }), _jsx(Count, { label: "Tasks running", value: data?.tasks.length ?? 0, to: routes.runs, onOpen: navigate }), _jsx(Count, { label: "Calls today", value: data?.today.calls ?? 0, to: routes.calls, onOpen: navigate }), _jsx(Count, { label: "Refusals today", value: data?.today.refusals ?? 0, to: routes.audit, onOpen: navigate, tone: (data?.today.refusals ?? 0) > 0 ? 'danger' : 'neutral' }), _jsx(Count, { label: "Credits by agents", value: data?.today.credits ?? 0, note: "today", 
+                            // Credits are summed from the day's calls, which the Calls tab
+                            // lists.
+                            to: routes.calls, onOpen: navigate })] }))), draws('agents') &&
                 !loading &&
                 (clients.length > 0 ? (_jsxs(Table.Container, { children: [_jsx(Table.Title, { as: "h3", id: "mcp-clients", children: "Connected clients" }), _jsxs(Table.Subtitle, { as: "p", id: "mcp-clients-subtitle", children: [plural(clients.length, 'client'), " with a live grant on your workspace."] }), _jsx(DataTable, { "aria-labelledby": "mcp-clients", "aria-describedby": "mcp-clients-subtitle", data: clients, columns: clientColumns })] })) : (_jsx(PanelEmpty, { icon: PlugIcon, heading: "No client connected", description: "Connect Claude Code, Codex, Cursor, VS Code or any MCP client to your workspace, and it appears here on its first call.", action: {
                         label: 'Set up a client',
@@ -396,12 +406,7 @@ export const McpDashboard = ({ errorState, routes, org, showTitle = true, sectio
                             }, children: "No call matches these filters." }))] })) : (_jsx(PanelEmpty, { icon: ChecklistIcon, heading: "No call yet", description: "Ask your agent to list your notebooks. The call, its decision and its outcome land here and in the audit log.", action: {
                         label: 'Open the audit log',
                         onClick: () => navigate(routes.audit),
-                    } }))), !loading && (_jsxs(Box, { sx: {
-                    display: 'flex',
-                    gap: 3,
-                    alignItems: 'center',
-                    flexWrap: 'wrap',
-                }, children: [_jsx(Button, { size: "small", leadingVisual: TelescopeIcon, onClick: () => navigate(routes.observability), children: "Observability" }), _jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: ["Refreshed ", timeAgo(data?.at) || 'just now', ", and again every ten seconds."] })] })), disconnecting && (_jsx(Dialog, { title: "Disconnect this client?", onClose: () => setDisconnecting(null), returnFocusRef: returnFocusRef, footerButtons: [
+                    } }))), disconnecting && (_jsx(Dialog, { title: "Disconnect this client?", onClose: () => setDisconnecting(null), returnFocusRef: returnFocusRef, footerButtons: [
                     {
                         buttonType: 'default',
                         content: 'Keep it',

package/lib/views/mcp/McpHome.js

@@ -1,8 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useState } from 'react';
+import { AiAgentIcon } from '@datalayer/icons-react';
 import { Button, Heading, IconButton, Link, Text } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
-import { CheckIcon, CopyIcon, KeyIcon, PlugIcon, PulseIcon, ShareIcon, TelescopeIcon, ToolsIcon, } from '@primer/octicons-react';
+import { CheckIcon, CopyIcon, KeyIcon, PulseIcon, RssIcon, ShieldCheckIcon, TelescopeIcon, ToolsIcon, } from '@primer/octicons-react';
 import { useConnectedAgents, useMcpActivity, useMcpMetrics, useTasks, } from '../../hooks/useMcp.js';
 import { useNavigate } from '../../hooks/index.js';
 import { useCoreStore, useIAMStore } from '../../state/index.js';
@@ -63,7 +64,7 @@ export const Copyable = ({ text }) => {
                 } })] }));
 };
 /** One of the five summaries: a heading, what it holds, and the way in. */
-const Summary = ({ icon: Icon, title, children, action, }) => (_jsxs(Box, { sx: {
+const Summary = ({ icon: Icon, title, children, action, to, onOpen, }) => (_jsxs(Box, { sx: {
         p: 3,
         border: '1px solid',
         borderColor: 'border.default',
@@ -72,7 +73,14 @@ const Summary = ({ icon: Icon, title, children, action, }) => (_jsxs(Box, { sx:
         gap: 2,
         alignContent: 'start',
         minWidth: 0,
-    }, children: [_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsx(Icon, { size: 16 }), _jsx(Text, { sx: { fontSize: 1, fontWeight: 'semibold' }, children: title })] }), _jsx(Box, { sx: { fontSize: 0, color: 'fg.muted', display: 'grid', gap: 1 }, children: children }), action && (_jsx(Box, { children: _jsx(Link, { as: "button", sx: { fontSize: 0, cursor: 'pointer' }, onClick: action.onClick, children: action.label }) }))] }));
+    }, children: [_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsx(Icon, { size: 16 }), to ? (_jsx(Link, { href: to, onClick: event => {
+                        // A modified click asks for a new tab; `href` is real, so let it.
+                        if (event.metaKey || event.ctrlKey || event.shiftKey) {
+                            return;
+                        }
+                        event.preventDefault();
+                        onOpen?.(to);
+                    }, sx: { fontSize: 1, fontWeight: 'semibold' }, children: title })) : (_jsx(Text, { sx: { fontSize: 1, fontWeight: 'semibold' }, children: title }))] }), _jsx(Box, { sx: { fontSize: 0, color: 'fg.muted', display: 'grid', gap: 1 }, children: children }), action && (_jsx(Box, { children: _jsx(Link, { as: "button", sx: { fontSize: 0, cursor: 'pointer' }, onClick: action.onClick, children: action.label }) }))] }));
 export const McpHome = ({ routes, clientDocsBase = '/docs/mcp-clients', showTitle = true, showSummaries = true, showSetup = true, onOpenDocs, }) => {
     const navigate = useNavigate();
     const endpoint = useCoreStore(state => state.configuration.datalayerMcpServerUrl);
@@ -130,12 +138,12 @@ export const McpHome = ({ routes, clientDocsBase = '/docs/mcp-clients', showTitl
                     display: 'grid',
                     gap: 3,
                     gridTemplateColumns: ['1fr', 'repeat(2, 1fr)', 'repeat(3, 1fr)'],
-                }, children: [_jsx(Summary, { icon: PlugIcon, title: "Agents", action: {
+                }, children: [_jsx(Summary, { icon: AiAgentIcon, title: "Agents", to: routes.agents, onOpen: navigate, action: {
                             label: 'Connected agents',
                             onClick: () => navigate(routes.agents),
                         }, children: connected.length === 0 ? (_jsx(Text, { children: "No agent has been authorized yet. Set up a client above and approve the scopes it asks for." })) : (_jsxs(_Fragment, { children: [_jsxs(Text, { children: [plural(connected.length, 'agent'), " authorized."] }), connected.slice(0, 3).map(agent => (_jsxs(Text, { children: [agent.clientName || agent.clientId, " \u2014", ' ', agent.lastUsedAt
                                             ? `used ${timeAgo(agent.lastUsedAt)}`
-                                            : 'never used'] }, agent.uid)))] })) }), _jsx(Summary, { icon: PulseIcon, title: "Runs", action: { label: 'All runs', onClick: () => navigate(routes.runs) }, children: runs.length === 0 ? (_jsx(Text, { children: "Nothing has run yet. A tool call that outlives its request becomes a run you can watch and cancel." })) : (runs.map(task => (_jsxs(Text, { children: [task.tool, " \u2014 ", task.status, " ", timeAgo(task.lastUpdatedAt)] }, task.uid)))) }), _jsxs(Summary, { icon: TelescopeIcon, title: "Observability", action: {
+                                            : 'never used'] }, agent.uid)))] })) }), _jsx(Summary, { icon: PulseIcon, title: "Runs", to: routes.runs, onOpen: navigate, action: { label: 'All runs', onClick: () => navigate(routes.runs) }, children: runs.length === 0 ? (_jsx(Text, { children: "Nothing has run yet. A tool call that outlives its request becomes a run you can watch and cancel." })) : (runs.map(task => (_jsxs(Text, { children: [task.tool, " \u2014 ", task.status, " ", timeAgo(task.lastUpdatedAt)] }, task.uid)))) }), _jsxs(Summary, { icon: TelescopeIcon, title: "Observability", to: routes.observability, onOpen: navigate, action: {
                             label: 'Runs and metrics',
                             onClick: () => navigate(routes.observability),
                         }, children: [_jsx(Text, { children: metrics.data?.slis.samples.calls
@@ -145,7 +153,7 @@ export const McpHome = ({ routes, clientDocsBase = '/docs/mcp-clients', showTitl
                                     : 'Latency not measured yet.' }), _jsx(Text, { children: metrics.data?.slis.availability === null ||
                                     metrics.data?.slis.availability === undefined
                                     ? 'Error rate not measured yet.'
-                                    : `${((1 - metrics.data.slis.availability) * 100).toFixed(1)}% of calls failed.` })] }), _jsx(Summary, { icon: ToolsIcon, title: "Tools", children: _jsx(Text, { children: "The toolsets an agent may execute \u2014 the Contents sources you have enabled for it, their tools, their approval policy and their health \u2014 are managed here once toolset bindings ship." }) }), _jsx(Summary, { icon: ShareIcon, title: "Reach", children: _jsx(Text, { children: "Which notebooks and sources an agent can actually reach, as a list you can read at a glance, arrives with sharing to agents as principals." }) }), _jsx(Summary, { icon: KeyIcon, title: "Policies", action: {
+                                    : `${((1 - metrics.data.slis.availability) * 100).toFixed(1)}% of calls failed.` })] }), _jsx(Summary, { icon: ToolsIcon, title: "Tools", children: _jsx(Text, { children: "The toolsets an agent may execute \u2014 the Contents sources you have enabled for it, their tools, their approval policy and their health \u2014 are managed here once toolset bindings ship." }) }), _jsx(Summary, { icon: RssIcon, title: "Reach", children: _jsx(Text, { children: "Which notebooks and sources an agent can actually reach, as a list you can read at a glance, arrives with sharing to agents as principals." }) }), _jsx(Summary, { icon: ShieldCheckIcon, title: "Policies", to: routes.policies, onOpen: navigate, action: {
                             label: 'What applies',
                             onClick: () => navigate(routes.policies),
                         }, children: _jsx(Text, { children: "What your agents are allowed to do, and which layer decided each rule." }) })] }))] }));

package/lib/views/mcp/types.d.ts

@@ -63,4 +63,8 @@ export interface McpRoutes {
     agents: string;
     /** The effective policy. */
     policies: string;
+    /** The calls list, where an Overview count of calls or credits leads. */
+    calls?: string;
+    /** The bound code sandboxes, where the Overview's sandbox count leads. */
+    sandboxes?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/core",
-    "version": "1.2.12",
+    "version": "1.2.14",
     "type": "module",
     "workspaces": [
         ".",
@@ -109,11 +109,11 @@
         "rebuild:fresh": "npm run create:patches && npm install && npm run build && npm run clean:cache"
     },
     "dependencies": {
-        "@datalayer/design": "^1.0.0",
-        "@datalayer/icons-react": "^1.0.7",
-        "@datalayer/jupyter-lexical": "^1.0.24",
-        "@datalayer/jupyter-react": "^2.0.15",
-        "@datalayer/primer-addons": "^1.0.15",
+        "@datalayer/design": "^1.0.3",
+        "@datalayer/icons-react": "^1.0.14",
+        "@datalayer/jupyter-lexical": "^2.0.18",
+        "@datalayer/jupyter-react": "^2.0.18",
+        "@datalayer/primer-addons": "^1.0.23",
         "@datalayer/primer-rjsf": "^1.0.3",
         "@fluentui/react": "^8.125.3",
         "@jupyter-widgets/base-manager": "^1.0.12",

package/scripts/generate-fluent-emoji.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+# Copyright (c) 2023-2025 Datalayer, Inc.
+# Distributed under the terms of the Modified BSD License.
+
+"""
+Write the Fluent Emoji drawings of the faces Datalayer offers (LOOP T-20).
+
+Reads the emojis between the ``fluent-emoji:start`` and ``fluent-emoji:end``
+markers of ``src/components/emoji/faceEmojis.ts``, finds each in Microsoft's
+Fluent Emoji (MIT) at a pinned commit by the unicode its metadata gives, and
+writes its *Flat* drawing as a module of its own under
+``src/components/emoji/fluent/svg/`` -- fetched on first draw, from
+Datalayer's own bundle -- with ``loaders.ts`` naming them all and the licence
+beside them. An emoji Fluent does not draw stops the script.
+
+Run from the repository's root::
+
+    python scripts/generate-fluent-emoji.py [--cache DIR]
+"""
+
+from __future__ import annotations
+
+import argparse
+import concurrent.futures
+import json
+import re
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+REPO = "microsoft/fluentui-emoji"
+COMMIT = "1ffb34c752ecf5d402f04cfb4b392c77f57c54bc"
+RAW = f"https://raw.githubusercontent.com/{REPO}/{COMMIT}/"
+TREE = f"https://api.github.com/repos/{REPO}/git/trees/{COMMIT}?recursive=1"
+
+ROOT = Path(__file__).resolve().parent.parent
+LIST = ROOT / "src/components/emoji/faceEmojis.ts"
+OUT = ROOT / "src/components/emoji/fluent"
+
+
+def fetch(url: str) -> bytes:
+    """
+    Fetch a URL of GitHub's.
+
+    Parameters
+    ----------
+    url : str
+        The URL, at the pinned commit.
+
+    Returns
+    -------
+    bytes
+        Its body.
+    """
+    with urllib.request.urlopen(url, timeout=60) as response:  # nosec B310
+        return response.read()
+
+
+def cached(cache: Path | None, name: str, url: str) -> bytes:
+    """
+    Fetch a URL once, keeping it under ``cache`` when one is given.
+
+    Parameters
+    ----------
+    cache : Path or None
+        Where to keep what was fetched.
+    name : str
+        The file it is kept as.
+    url : str
+        The URL.
+
+    Returns
+    -------
+    bytes
+        Its body.
+    """
+    if cache is None:
+        return fetch(url)
+    path = cache / name
+    if not path.exists():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(fetch(url))
+    return path.read_bytes()
+
+
+def key_of(codes: list[int]) -> str:
+    """
+    Name a drawing as ``emojiKey`` does in ``faceEmojis.ts``.
+
+    Parameters
+    ----------
+    codes : list of int
+        The emoji's code points.
+
+    Returns
+    -------
+    str
+        Lower-case hexadecimal code points joined by ``-``, without U+FE0F.
+    """
+    return "-".join(f"{code:x}" for code in codes if code != 0xFE0F)
+
+
+def main() -> None:
+    """Write the drawings, their loaders and the licence."""
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[1])
+    parser.add_argument("--cache", type=Path, help="keep what is fetched here")
+    args = parser.parse_args()
+
+    text = LIST.read_text(encoding="utf-8")
+    block = text.split("// fluent-emoji:start", 1)[1].split("// fluent-emoji:end", 1)[0]
+    emojis = re.findall(r"^\s*'([^']+)',", block, flags=re.M)
+    keys = list(dict.fromkeys(key_of([ord(c) for c in emoji]) for emoji in emojis))
+
+    tree = json.loads(cached(args.cache, "tree.json", TREE))["tree"]
+    paths = [item["path"] for item in tree if item["type"] == "blob"]
+    metadata = [p for p in paths if p.count("/") == 2 and p.endswith("/metadata.json")]
+
+    def read(path: str) -> tuple[str, dict]:
+        name = "meta/" + path.split("/")[1] + ".json"
+        return path.split("/")[1], json.loads(cached(args.cache, name, RAW + urllib.parse.quote(path)))
+
+    with concurrent.futures.ThreadPoolExecutor(16) as pool:
+        folders = dict(pool.map(read, metadata))
+    by_key = {
+        key_of([int(code, 16) for code in meta.get("unicode", "").split()]): (folder, meta)
+        for folder, meta in folders.items()
+    }
+
+    missing = [key for key in keys if key not in by_key]
+    if missing:
+        raise SystemExit(f"Fluent Emoji draws none of: {', '.join(missing)}")
+
+    (OUT / "svg").mkdir(parents=True, exist_ok=True)
+    for stale in (OUT / "svg").glob("*.ts"):
+        stale.unlink()
+    (OUT / "LICENSE").write_bytes(cached(args.cache, "LICENSE", RAW + "LICENSE"))
+
+    loaders = []
+    for key in keys:
+        folder, meta = by_key[key]
+        # The one drawing, or, for an emoji with skin tones, the default's.
+        flat = [
+            p
+            for p in paths
+            if p.startswith(f"assets/{folder}/Flat/")
+            or p.startswith(f"assets/{folder}/Default/Flat/")
+        ]
+        flat = [p for p in flat if p.endswith(".svg")]
+        if len(flat) != 1:
+            raise SystemExit(f"{folder}: {len(flat)} Flat drawings, not one")
+        svg = cached(args.cache, f"svg/{key}.svg", RAW + urllib.parse.quote(flat[0])).decode("utf-8")
+        svg = re.sub(r"\s*\n\s*", " ", svg.strip())
+        # In single quotes, as prettier writes a string with no quote of its own.
+        quoted = "'" + svg.replace("\\", "\\\\").replace("'", "\\'") + "'"
+        (OUT / "svg" / f"{key}.ts").write_text(
+            "/*\n"
+            f" * {meta['glyph']} {meta.get('cldr', folder)} — Fluent Emoji, Flat, by Microsoft (MIT,\n"
+            " * see ../LICENSE). Written by scripts/generate-fluent-emoji.py: do not edit.\n"
+            " */\n\n"
+            f"export default {quoted};\n",
+            encoding="utf-8",
+        )
+        loaders.append(f"  '{key}': () => import('./svg/{key}'),")
+
+    (OUT / "loaders.ts").write_text(
+        "/*\n"
+        " * Copyright (c) 2023-2025 Datalayer, Inc.\n"
+        " * Distributed under the terms of the Modified BSD License.\n"
+        " */\n\n"
+        "/**\n"
+        " * The Fluent Emoji drawings Datalayer ships, by `emojiKey`, each a module\n"
+        " * of its own, fetched the first time it is drawn. The drawings are\n"
+        f" * Microsoft's Fluent Emoji (MIT, see ./LICENSE), at {REPO}@{COMMIT[:12]}.\n"
+        " * Written by scripts/generate-fluent-emoji.py: do not edit.\n"
+        " *\n"
+        " * @module components/emoji/fluent/loaders\n"
+        " */\n\n"
+        f"export const FLUENT_EMOJI_COMMIT = '{COMMIT}';\n\n"
+        "export const FLUENT_EMOJI_LOADERS: Readonly<\n"
+        "  Record<string, () => Promise<{ default: string }>>\n"
+        "> = {\n" + "\n".join(loaders) + "\n};\n",
+        encoding="utf-8",
+    )
+    print(f"{len(keys)} drawings written to {OUT.relative_to(ROOT)}")
+
+
+if __name__ == "__main__":
+    main()