@datalayer/core 1.2.19 → 1.2.21

package/lib/api/evals/client.d.ts

@@ -15,7 +15,7 @@ export type ListEvalsetsQuery = {
     run_environment?: EvalRunEnvironment;
     category?: EvalsetCategory;
     q?: string;
-    /** Only the benchmarks reading this dataset (B5-12, section 15.3). */
+    /** Only the benchmarks reading this dataset (B5-12). */
     dataset?: string;
     /** …and pinned to this revision of it: one revision is not evidence about another. */
     revision?: string;
@@ -68,8 +68,8 @@ export declare const previewEvalsetPublication: (options: EvalsClientOptions, ev
 /**
  * Publish the package: the immutable snapshot of the definition, the data, the
  * subjects, the environment, the results, the report, the evidence and the
- * evaluators (section 14.3). Refused with `detail.problems` where section 14.5
- * says it cannot be published.
+ * evaluators. Refused with `detail.problems` where something stands in the
+ * way of publishing it.
  */
 export declare const publishEvalsetPackage: (options: EvalsClientOptions, evalsetId: string, body?: {
     launch_ids?: string[];
@@ -118,13 +118,13 @@ export declare const getPublicEvalsetLeaderboard: (options: EvalsClientOptions,
  */
 export declare const getSubjectUsage: (options: EvalsClientOptions, subjectRef: string) => Promise<SubjectUsageResponse>;
 /**
- * Whether anything will run the account's benchmarks (B5-12, section 15.2):
+ * Whether anything will run the account's benchmarks (B5-12):
  * the executor, whether a worker polls the benchmark queue, and the account's
  * own queued and running launches.
  */
 export declare const getBenchmarkCompute: (options: EvalsClientOptions) => Promise<BenchmarkComputeResponse>;
 /**
- * What benchmark work a sandbox is doing (B5-12, section 15.4).
+ * What benchmark work a sandbox is doing (B5-12).
  *
  * The ref is a pool slot's name (`benchmark-<run>-slot-<n>`) or the snapshot
  * a sandbox was restored from. A sandbox of nobody's benchmark answers
@@ -132,7 +132,7 @@ export declare const getBenchmarkCompute: (options: EvalsClientOptions) => Promi
  */
 export declare const getSandboxProvenance: (options: EvalsClientOptions, sandboxRef: string) => Promise<SandboxProvenanceResponse>;
 /**
- * Find things across the caller's benchmarks (B5-11, section 19): benchmarks,
+ * Find things across the caller's benchmarks (B5-11): benchmarks,
  * launches, tasks, reports and investigations, each row keeping its kind and
  * what it belongs to.
  *

package/lib/api/evals/client.js

@@ -58,8 +58,8 @@ export const previewEvalsetPublication = (options, evalsetId, query = {}) => eva
 /**
  * Publish the package: the immutable snapshot of the definition, the data, the
  * subjects, the environment, the results, the report, the evidence and the
- * evaluators (section 14.3). Refused with `detail.problems` where section 14.5
- * says it cannot be published.
+ * evaluators. Refused with `detail.problems` where something stands in the
+ * way of publishing it.
  */
 export const publishEvalsetPackage = (options, evalsetId, body = {}) => evalsRequest(options, `/evalsets/${segment(evalsetId)}/publications`, {
     method: 'POST',
@@ -97,13 +97,13 @@ export const getPublicEvalsetLeaderboard = (options, evalsetId) => evalsRequest(
  */
 export const getSubjectUsage = (options, subjectRef) => evalsRequest(options, `/subjects/${subjectRef.split('/').map(encodeURIComponent).join('/')}/usage`);
 /**
- * Whether anything will run the account's benchmarks (B5-12, section 15.2):
+ * Whether anything will run the account's benchmarks (B5-12):
  * the executor, whether a worker polls the benchmark queue, and the account's
  * own queued and running launches.
  */
 export const getBenchmarkCompute = (options) => evalsRequest(options, '/compute/operations');
 /**
- * What benchmark work a sandbox is doing (B5-12, section 15.4).
+ * What benchmark work a sandbox is doing (B5-12).
  *
  * The ref is a pool slot's name (`benchmark-<run>-slot-<n>`) or the snapshot
  * a sandbox was restored from. A sandbox of nobody's benchmark answers
@@ -111,7 +111,7 @@ export const getBenchmarkCompute = (options) => evalsRequest(options, '/compute/
  */
 export const getSandboxProvenance = (options, sandboxRef) => evalsRequest(options, `/sandboxes/${sandboxRef.split('/').map(encodeURIComponent).join('/')}/provenance`);
 /**
- * Find things across the caller's benchmarks (B5-11, section 19): benchmarks,
+ * Find things across the caller's benchmarks (B5-11): benchmarks,
  * launches, tasks, reports and investigations, each row keeping its kind and
  * what it belongs to.
  *

package/lib/api/evals/status.d.ts

@@ -5,7 +5,7 @@
  * time (`queued`, `init`, `pending`, `running`, `completed`, `failed`,
  * `error`, `success`, `done`, …). This is the same mapping as
  * `agent_runtimes.evals.status` in Python: every word a writer has used maps
- * onto the product vocabulary of BENCHMARK.md section 11.4, and "finished" is
+ * onto the product vocabulary, and "finished" is
  * answered once. A word nobody has used maps to itself, lower-cased, so it is
  * visible rather than misread.
  *
@@ -17,9 +17,9 @@ export declare const CASE_STATUSES: readonly ["waiting", "provisioning", "runnin
 export type CaseStatus = (typeof CASE_STATUSES)[number];
 export declare const TERMINAL_RUN_STATUSES: ReadonlySet<string>;
 export declare const TERMINAL_CASE_STATUSES: ReadonlySet<string>;
-/** The section 11.4 word for a run status, whatever a writer wrote. */
+/** The product word for a run status, whatever a writer wrote. */
 export declare const normalizeRunStatus: (value: unknown) => RunStatus | string;
-/** The section 11.4 word for a case status. */
+/** The product word for a case status. */
 export declare const normalizeCaseStatus: (value: unknown) => CaseStatus | string;
 /** Whether a run with this status is over. */
 export declare const isTerminalRunStatus: (value: unknown) => boolean;

package/lib/api/evals/status.js

@@ -13,7 +13,7 @@
  * time (`queued`, `init`, `pending`, `running`, `completed`, `failed`,
  * `error`, `success`, `done`, …). This is the same mapping as
  * `agent_runtimes.evals.status` in Python: every word a writer has used maps
- * onto the product vocabulary of BENCHMARK.md section 11.4, and "finished" is
+ * onto the product vocabulary, and "finished" is
  * answered once. A word nobody has used maps to itself, lower-cased, so it is
  * visible rather than misread.
  *
@@ -106,12 +106,12 @@ const word = (value) => String(value ?? '')
     .trim()
     .toLowerCase()
     .replace(/[-\s]/g, '_');
-/** The section 11.4 word for a run status, whatever a writer wrote. */
+/** The product word for a run status, whatever a writer wrote. */
 export const normalizeRunStatus = (value) => {
     const key = word(value);
     return LEGACY_RUN_STATUS[key] ?? key;
 };
-/** The section 11.4 word for a case status. */
+/** The product word for a case status. */
 export const normalizeCaseStatus = (value) => {
     const key = word(value);
     return LEGACY_CASE_STATUS[key] ?? key;

package/lib/api/evals/types.d.ts

@@ -17,7 +17,7 @@
 export type EvalRunEnvironment = 'ui' | 'sdk';
 /** Fixed cases replayed (`batch`) or live events evaluated (`interactive`). */
 export type EvalKind = 'batch' | 'interactive';
-/** What a benchmark measures, the closed list section 12.5 renders by. */
+/** What a benchmark measures, the closed list the benchmark pages render by. */
 export type EvalsetCategory = 'data' | 'coding' | 'tool-use' | 'model' | 'visual' | 'performance';
 /** The dataset revision a benchmark reads; contents holds the revision. */
 export interface DatasetRef {
@@ -285,7 +285,7 @@ export interface LaunchPlanResponse {
     /**
      * How run mode, run environment and execution target relate, stated by
      * the service so the wizard explains it inline rather than failing after
-     * submission (BENCHMARK.md section 9).
+     * submission.
      */
     run_mode_constraint: string;
     problems: LaunchPlanProblem[];
@@ -466,7 +466,7 @@ export interface EvalsetPackageItem {
     uid: string;
     label: string;
 }
-/** What stands in the way of a publication (section 14.5). */
+/** What stands in the way of a publication. */
 export interface EvalsetPackageProblem {
     code: string;
     detail: string;
@@ -636,7 +636,7 @@ export interface SubjectUsage {
     active_launches: SubjectLaunch[];
     totals: SubjectTotals;
 }
-/** What a search made of the words somebody typed (B5-11, section 19). */
+/** What a search made of the words somebody typed (B5-11). */
 export interface EvalsSearchQuery {
     raw: string;
     /** What is left to look for by name, once the words that mean something else are taken out. */
@@ -676,7 +676,7 @@ export interface SubjectUsageResponse {
     usage: SubjectUsage;
 }
 /**
- * What benchmark work a sandbox is doing (B5-12, section 15.4).
+ * What benchmark work a sandbox is doing (B5-12).
  *
  * A pool slot's sandbox is named after the run it serves, and a sandbox
  * restored from a task's snapshot is found by that snapshot; either way the
@@ -723,7 +723,7 @@ export interface SandboxProvenanceResponse {
     provenance: SandboxProvenance;
 }
 /**
- * Whether anything will run the account's benchmarks (B5-12, section 15.2).
+ * Whether anything will run the account's benchmarks (B5-12).
  *
  * A launch at `queued` looks the same whether the queue is busy or nothing
  * polls it. `serving` is the difference. The depth is the account's own
@@ -1050,7 +1050,7 @@ export interface EvalsetVersionResponse {
 }
 export type InvestigationScope = 'case' | 'run' | 'launch' | 'window';
 export type InvestigationStatus = 'open' | 'closed';
-/** The restored sandbox, per section 12.6. */
+/** The restored sandbox. */
 export type SandboxState = 'available' | 'restoring' | 'running' | 'expired' | 'none';
 /** The work a person does on a benchmark result: one per task, run, launch or window. */
 export interface EvalInvestigation {
@@ -1165,7 +1165,7 @@ export interface EvalsSharingResponse extends SuccessResponse {
     };
 }
 /**
- * How far a record reaches (BENCHMARKS.md, B5-09, section 14.5), narrowest
+ * How far a record reaches (B5-09), narrowest
  * first. Derived from the grants and the public flag rather than stored, so it
  * cannot disagree with who may actually read the thing.
  */
@@ -1178,7 +1178,7 @@ export interface EvalsPermissionsResponse extends SuccessResponse {
     /** The widest thing that is true of this record. */
     visibility: EvalsVisibility;
 }
-/** The states of a report (section 13.3), in the order a report goes through them. */
+/** The states of a report, in the order a report goes through them. */
 export type ReportState = 'draft' | 'in_review' | 'approved' | 'published_private' | 'published_public' | 'superseded';
 /** A report over runs of one benchmark: its document and its state. */
 export interface EvalReport {

package/lib/api/iam/secrets.js

@@ -36,8 +36,8 @@ export const createSecret = async (token, data, baseUrl = DEFAULT_SERVICE_URLS.I
         variant: data.variant || 'generic',
         name: data.name,
         description: data.description || '',
-        // As it is. A secret has one representation end to end (PLAN_ENVS.md
-        // E3-05): this used to base64-encode, and nothing on the read side undid
+        // As it is. A secret has one representation end to end (E3-05):
+        // this used to base64-encode, and nothing on the read side undid
         // it, so a build secret arrived at its build encoded and opened nothing.
         value: data.value,
     };

package/lib/api/iam/servicePrincipals.js

@@ -4,7 +4,7 @@
  */
 /**
  * Service principals: a deployed LOOP application as a principal of its
- * own (plans/LOOP.md, I-02).
+ * own (I-02).
  *
  * The service agents' kin — a key that is exchanged for an hour's token, an
  * audit that names it — with two differences: a person may own one, not only

package/lib/api/iam/trials.js

@@ -8,7 +8,7 @@
  */
 /**
  * The anonymous trial: running the public benchmark before signing up
- * (BENCHMARK.md, B2-14).
+ * (B2-14).
  *
  * A visitor with no account asks for a trial and gets a principal of its
  * own with one benchmark it may run, a few credits and a short expiry. The

package/lib/api/orchestration/generated.d.ts

@@ -11,7 +11,7 @@ export interface Acknowledgement {
     checkpointId?: string | null;
     detail?: string | null;
 }
-/** The five milestones of section 6.3, in the order they are reached. */
+/** The five acknowledgement milestones, in the order they are reached. */
 export type AcknowledgementKind = 'received' | 'accepted' | 'started' | 'checkpointed' | 'completed';
 /** What a caller must present to be let in. */
 export interface AgentAuthentication {
@@ -148,11 +148,11 @@ export interface ArtifactProvenance {
     contentHash?: string | null;
     traceId?: string | null;
 }
-/** Where an artifact stands against the commit rule of 19.8. */
+/** Where an artifact stands against the commit rule: the first attempt to commit wins. */
 export type ArtifactStatus = 'registered' | 'committed' | 'superseded';
-/** What an artifact is, from the nine kinds of section 5.4. */
+/** What an artifact is, one of nine kinds. */
 export type ArtifactType = 'notebook' | 'report' | 'dataset' | 'cell-output' | 'file' | 'evaluation' | 'execution-log' | 'sandbox-snapshot' | 'json';
-/** One dispatch of an execution to a worker (section 6.4). */
+/** One dispatch of an execution to a worker. */
 export interface Attempt {
     attemptId: string;
     executionId: string;
@@ -227,7 +227,7 @@ export interface CommandAnswer {
     execution: Execution;
     success?: boolean;
 }
-/** The twelve commands of section 6.2. */
+/** The twelve commands of the orchestration lifecycle. */
 export type CommandName = 'agents.discover' | 'agents.create' | 'agents.attach' | 'executions.delegate' | 'executions.steer' | 'executions.pause' | 'executions.resume' | 'executions.cancel' | 'executions.checkpoint' | 'executions.collect' | 'executions.terminate' | 'executions.subscribe';
 /** Whether a worker may only read the reference, or also write it. */
 export type ContextAccess = 'read-only' | 'writable';
@@ -272,7 +272,7 @@ export interface DelegateAnswer {
     execution: Execution;
     success?: boolean;
 }
-/** The bounds a tree is created under, defaulted to 19.8's decision. */
+/** The bounds a tree is created under, with the decided defaults. */
 export interface DelegationLimits {
     maxDepth?: number;
     maxChildrenPerParent?: number;
@@ -588,7 +588,7 @@ export interface ReportAnswer {
     execution: Execution;
     success?: boolean;
 }
-/** How a failed attempt is tried again: 19.8's two retries, backing off. */
+/** How a failed attempt is tried again: two retries, backing off. */
 export interface RetryPolicy {
     maxRetries?: number;
     initialBackoffSeconds?: number;
@@ -604,7 +604,7 @@ export interface RuntimeRequirements {
     /** A Datalayer runtime environment name, when it runs on one. */
     environment?: string | null;
 }
-/** The W3C context that makes one tree one trace (section 10, O0-11). */
+/** The W3C context that makes one tree one trace (O0-11). */
 export interface Trace {
     traceparent?: string | null;
     tracestate?: string | null;
@@ -649,9 +649,9 @@ export interface WorkerAnswer {
     success?: boolean;
     worker: Worker;
 }
-/** A lifecycle operation a worker supports, named as section 6.2 names it. */
+/** A lifecycle operation a worker supports, named as the orchestration lifecycle names it. */
 export type WorkerOperation = 'delegate' | 'steer' | 'pause' | 'resume' | 'cancel' | 'checkpoint' | 'collect' | 'terminate' | 'subscribe';
-/** The lifecycle of section 6.1: what a state accepts, and where it leads. */
+/** The lifecycle: what a state accepts, and where it leads. */
 export interface OrchestrationLifecycle {
     readonly initial: ExecutionState;
     readonly states: readonly ExecutionState[];
@@ -668,9 +668,9 @@ export interface OrchestrationCommand {
     readonly mutating: boolean;
 }
 export declare const ORCHESTRATION_COMMANDS: readonly OrchestrationCommand[];
-/** The five milestones of section 6.3, in the order they are reached. */
+/** The five milestones, in the order they are reached. */
 export declare const ORCHESTRATION_ACKNOWLEDGEMENT_ORDER: readonly AcknowledgementKind[];
-/** The default limits of 19.8, read from the models' own defaults. */
+/** The default limits, read from the models' own defaults. */
 export interface OrchestrationLimits {
     readonly delegation: DelegationLimits;
     readonly retry: RetryPolicy;

package/lib/api/orchestration/generated.js

@@ -91,7 +91,7 @@ export const ORCHESTRATION_COMMANDS = [
     { name: 'executions.terminate', mutating: true },
     { name: 'executions.subscribe', mutating: false },
 ];
-/** The five milestones of section 6.3, in the order they are reached. */
+/** The five milestones, in the order they are reached. */
 export const ORCHESTRATION_ACKNOWLEDGEMENT_ORDER = ['received', 'accepted', 'started', 'checkpointed', 'completed'];
 export const ORCHESTRATION_LIMITS = {
     delegation: {

package/lib/api/orchestration/index.d.ts

@@ -3,8 +3,8 @@
  * work it is delegating, supervising, steering, recovering or stopping.
  *
  * Every type here is generated from the pydantic models in
- * `datalayer_core/orchestration`, which are the source of truth
- * (PLAN_ORCHESTRATOR.md, 19.8), and from the control plane's OpenAPI
+ * `datalayer_core/orchestration`, which are the source of truth,
+ * and from the control plane's OpenAPI
  * document for the answers it wraps them in and the operations it serves.
  * Regenerate with `npm run generate:orchestration`;
  * `npm run check:orchestration-generated` is the gate that fails when the

package/lib/api/orchestration/index.js

@@ -7,8 +7,8 @@
  * work it is delegating, supervising, steering, recovering or stopping.
  *
  * Every type here is generated from the pydantic models in
- * `datalayer_core/orchestration`, which are the source of truth
- * (PLAN_ORCHESTRATOR.md, 19.8), and from the control plane's OpenAPI
+ * `datalayer_core/orchestration`, which are the source of truth,
+ * and from the control plane's OpenAPI
  * document for the answers it wraps them in and the operations it serves.
  * Regenerate with `npm run generate:orchestration`;
  * `npm run check:orchestration-generated` is the gate that fails when the

package/lib/api/orchestration/lifecycle.d.ts

@@ -1,5 +1,5 @@
 /**
- * The canonical execution lifecycle (PLAN_ORCHESTRATOR.md, section 6.1, O0-02).
+ * The canonical execution lifecycle (O0-02).
  *
  * The states and the moves between them are not written here: they are
  * generated from `datalayer_core/orchestration/lifecycle.py`, which is the

package/lib/api/orchestration/lifecycle.js

@@ -3,7 +3,7 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * The canonical execution lifecycle (PLAN_ORCHESTRATOR.md, section 6.1, O0-02).
+ * The canonical execution lifecycle (O0-02).
  *
  * The states and the moves between them are not written here: they are
  * generated from `datalayer_core/orchestration/lifecycle.py`, which is the

package/lib/api/scheduler/client.d.ts

@@ -17,7 +17,7 @@ export declare const listSchedules: (options: SchedulerClientOptions, query?: {
 /** One schedule. */
 export declare const getSchedule: (options: SchedulerClientOptions, scheduleUid: string) => Promise<ScheduleResponse>;
 /**
- * Create the one schedule a target has, or replace it (BENCHMARK.md, B2-16):
+ * Create the one schedule a target has, or replace it (B2-16):
  * a schedule is unique per owner and target, so upserting is how a person
  * changes an `evalset` schedule's cron or configuration too.
  */

package/lib/api/scheduler/client.js

@@ -24,7 +24,7 @@ export const listSchedules = (options, query = {}) => schedulerRequest(options,
 /** One schedule. */
 export const getSchedule = (options, scheduleUid) => schedulerRequest(options, `/schedules/${scheduleSegment(scheduleUid)}`);
 /**
- * Create the one schedule a target has, or replace it (BENCHMARK.md, B2-16):
+ * Create the one schedule a target has, or replace it (B2-16):
  * a schedule is unique per owner and target, so upserting is how a person
  * changes an `evalset` schedule's cron or configuration too.
  */

package/lib/api/scheduler/types.d.ts

@@ -33,7 +33,7 @@ export interface ScheduleRecord {
     creation_ts_dt?: string;
     last_update_ts_dt?: string;
 }
-/** What an `evalset` schedule's `config_json_t` holds (BENCHMARK.md, B2-16). */
+/** What an `evalset` schedule's `config_json_t` holds (B2-16). */
 export interface EvalsetScheduleConfig {
     /** Empty means every live experiment of the evalset, resolved at run time. */
     experiment_ids?: string[];

package/lib/api/spacer/comments.d.ts

@@ -1,5 +1,5 @@
 /**
- * Comments on documents and notebooks (BENCHMARK.md, B4-01).
+ * Comments on documents and notebooks (B4-01).
  *
  * A thread is its first comment, about one anchor — the highlighted text, a
  * report's evidence block, a cell, a task, a data point — and a reply names

package/lib/api/spacer/comments.js

@@ -7,7 +7,7 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * Comments on documents and notebooks (BENCHMARK.md, B4-01).
+ * Comments on documents and notebooks (B4-01).
  *
  * A thread is its first comment, about one anchor — the highlighted text, a
  * report's evidence block, a cell, a task, a data point — and a reply names

package/lib/api/spacer/spaces.d.ts

@@ -55,7 +55,7 @@ export interface WorkspaceSearchResponse {
 }
 /**
  * Search the caller's own workspace: notebooks, documents, datasets, files
- * (BENCHMARKS.md, B5-11, section 19).
+ * (B5-11).
  *
  * Scoped by the service to what this person may open — never other people's
  * public items, which the Library's own search answers. An empty query lists

package/lib/api/spacer/spaces.js

@@ -34,7 +34,7 @@ export const getManagedSpace = async (options, kind, accountUid) => {
 };
 /**
  * Search the caller's own workspace: notebooks, documents, datasets, files
- * (BENCHMARKS.md, B5-11, section 19).
+ * (B5-11).
  *
  * Scoped by the service to what this person may open — never other people's
  * public items, which the Library's own search answers. An empty query lists

package/lib/components/avatars/UserAvatar.d.ts

@@ -1,10 +1,10 @@
 /**
  * UserAvatar – Single source of truth for rendering a user's avatar.
  *
- * When a real (non-Gravatar) avatar URL is available it renders a
- * {@link DLAvatar}. Otherwise it falls back to a themed, colormoded
- * {@link AlienIcon} placeholder so every consumer (profile, sidebar,
- * principal overlay, …) shares the same default look.
+ * Drawn by primer-addons' `EntityAvatar`, so its ground, shape and ring are
+ * the theme's — a person's emoji, chosen icon or photograph, or a themed,
+ * colormoded {@link AlienIcon} placeholder, so every consumer (profile,
+ * sidebar, principal overlay, …) shares the same look, in every theme.
  */
 import type { JSX } from 'react';
 /**
@@ -14,14 +14,13 @@ import type { JSX } from 'react';
 export declare function hasRealAvatar(url?: string): boolean;
 export type UserAvatarProps = {
     avatarUrl?: string;
-    avatarIcon?: string;
     /**
-     * A literal emoji, checked before `avatarIcon`/`avatarUrl` — an agent's
-     * face is its emoji, not a photograph or a chosen icon standing in for
-     * one. Drawn in Fluent Emoji, the same on every platform (LOOP T-20); the
-     * system's, as text, only for one Datalayer ships no drawing of.
+     * The chosen avatar, as it is kept (`components/avatars/avatarChoice`):
+     * `emoji:👀` — drawn in Fluent Emoji, the same on every platform (LOOP
+     * T-20) — or `@datalayer/icons-react:RobotIcon`. Checked before
+     * `avatarUrl`: a chosen picture wins over a photograph.
      */
-    avatarEmoji?: string;
+    avatar?: string;
     /** Avatar edge length in pixels. Defaults to 100. */
     size?: number;
     /** Render with rounded square corners instead of a circle. Defaults to true. */
@@ -42,5 +41,5 @@ export type UserAvatarProps = {
     ring?: boolean;
     className?: string;
 };
-export declare const UserAvatar: ({ avatarUrl, avatarIcon, avatarEmoji, size, square, iconSize, fallbackBackground, fallbackForeground, ring, className, }: UserAvatarProps) => JSX.Element;
+export declare const UserAvatar: ({ avatarUrl, avatar, size, square, iconSize, fallbackBackground, fallbackForeground, ring, className, }: UserAvatarProps) => JSX.Element;
 export default UserAvatar;

package/lib/components/avatars/UserAvatar.js

@@ -1,9 +1,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { AlienIcon } from '@datalayer/icons-react';
-import { Box, useColorPalette } from '@datalayer/primer-addons';
-import { DLAvatar } from './DLAvatar.js';
-import { getPrincipalAvatarIcon } from '../principal/PrincipalAppearance.js';
-import { FluentEmoji } from '../emoji/FluentEmoji.js';
+import { EntityAvatar, useColorPalette } from '@datalayer/primer-addons';
+import { getAvatarURL } from '../../utils/index.js';
+import { ChosenAvatar, principalAvatarOf, } from '../principal/PrincipalAppearance.js';
 /**
  * Returns `true` when the given URL points to a real user avatar (i.e. not a
  * Gravatar default placeholder).
@@ -17,35 +16,31 @@ export function hasRealAvatar(url) {
     }
     return true;
 }
-export const UserAvatar = ({ avatarUrl, avatarIcon, avatarEmoji, size = 100, square = true, iconSize, fallbackBackground, fallbackForeground, ring = false, className, }) => {
+export const UserAvatar = ({ avatarUrl, avatar, size = 100, square = true, iconSize, fallbackBackground, fallbackForeground, ring = false, className, }) => {
     const palette = useColorPalette();
+    // A rounded square takes the theme's corner, a circle is a circle; the
+    // ring is drawn just outside the edge, so the avatar keeps its size.
+    const shape = square ? 'rounded' : 'circle';
+    const chosen = principalAvatarOf(avatar);
+    if (chosen?.kind === 'emoji') {
+        return (_jsx(EntityAvatar, { alt: chosen.emoji, className: className, size: size, shape: shape, ring: ring, bg: fallbackBackground || 'canvas.default', children: _jsx(ChosenAvatar, { avatar: avatar, size: iconSize ?? Math.round(size * 0.6) }) }));
+    }
     /*
-     * The ring, as a shadow rather than a border.
-     *
-     * A border would take from the size asked for — the avatar is laid out
-     * against others of the same measure — so it is drawn just outside the
-     * edge instead, following whatever shape the avatar has.
+     * A chosen icon and the default one are the same drawing in two shapes:
+     * the plain icon, coloured by the theme, on the accent's wash.
      */
-    const ringSx = ring
-        ? { boxShadow: '0 0 0 1px var(--borderColor-default, currentColor)' }
-        : undefined;
-    if (avatarEmoji) {
-        return (_jsx(Box, { role: "img", "aria-label": avatarEmoji, className: className, width: size, height: size, borderRadius: square ? 2 : '50%', display: "flex", alignItems: "center", justifyContent: "center", bg: fallbackBackground || 'canvas.default', sx: ringSx, children: _jsx(FluentEmoji, { emoji: avatarEmoji, size: iconSize ?? Math.round(size * 0.6), label: "" }) }));
-    }
-    const SelectedIcon = getPrincipalAvatarIcon(avatarIcon);
-    if (SelectedIcon) {
-        return (_jsx(Box, { className: className, width: size, height: size, borderRadius: square ? 2 : '50%', overflow: "hidden", display: "flex", alignItems: "center", justifyContent: "center", bg: fallbackBackground || 'accent.subtle', sx: {
-                '--datalayer-icon-fg': fallbackForeground || palette.primary,
-                ...ringSx,
-            }, children: _jsx(SelectedIcon, { size: iconSize ?? Math.round(size * 0.62), themed: true, colormode: true }) }));
+    const iconGround = {
+        ...(fallbackBackground ? { bg: fallbackBackground } : undefined),
+        style: {
+            '--datalayer-icon-fg': fallbackForeground || palette.primary,
+        },
+    };
+    if (chosen?.kind === 'icon') {
+        return (_jsx(EntityAvatar, { className: className, size: size, shape: shape, ring: ring, ...iconGround, children: _jsx(ChosenAvatar, { avatar: avatar, size: iconSize ?? Math.round(size * 0.62) }) }));
     }
     if (hasRealAvatar(avatarUrl)) {
-        return (_jsx(DLAvatar, { className: className, square: square, src: avatarUrl, size: size, sx: ringSx }));
+        return (_jsx(EntityAvatar, { className: className, src: getAvatarURL(avatarUrl), size: size, shape: shape, ring: ring }));
     }
-    const resolvedIconSize = iconSize ?? Math.round(size * 0.48);
-    return (_jsx(Box, { className: className, width: size, height: size, borderRadius: square ? 2 : '50%', bg: fallbackBackground || 'accent.subtle', display: "flex", alignItems: "center", justifyContent: "center", sx: {
-            '--datalayer-icon-fg': fallbackForeground || palette.primary,
-            ...ringSx,
-        }, children: _jsx(AlienIcon, { size: resolvedIconSize, themed: true, colormode: true }) }));
+    return (_jsx(EntityAvatar, { className: className, size: size, shape: shape, ring: ring, ...iconGround, children: _jsx(AlienIcon, { size: iconSize ?? Math.round(size * 0.48), themed: true, colormode: true }) }));
 };
 export default UserAvatar;

package/lib/components/avatars/UserProfileAvatar.js

@@ -8,7 +8,7 @@ import { Box } from '@datalayer/primer-addons';
 import { AvatarSkeleton } from '../../components/display/index.js';
 import { UserAvatar } from './UserAvatar.js';
 const Profile = ({ user, size = 100, onClick }) => {
-    return (_jsx(Box, { style: { width: size }, onClick: onClick, children: _jsx(UserAvatar, { avatarUrl: user?.avatarUrl, avatarIcon: user?.avatarIcon, size: size }) }));
+    return (_jsx(Box, { style: { width: size }, onClick: onClick, children: _jsx(UserAvatar, { avatarUrl: user?.avatarUrl, avatar: user?.avatarIcon, size: size }) }));
 };
 export const UserProfileAvatar = ({ onClick, user, size = 100, }) => {
     return user ? (onClick ? (_jsx(Link, { href: "javascript: return false;", onClick: onClick, children: _jsx(Profile, { user: user, size: size, onClick: onClick }) })) : (_jsx(Profile, { user: user, size: size, onClick: onClick }))) : (_jsx(AvatarSkeleton, { size: size }));

package/lib/components/avatars/avatarChoice.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The avatar a person, an organization, a team or an application chose, as it
+ * is kept: one string, prefixed by what it is.
+ *
+ * - `emoji:👀` — an emoji, drawn in Fluent Emoji (`FluentEmoji`);
+ * - `@datalayer/icons-react:RobotIcon` — a drawing of the avatar set
+ *   (`PRINCIPAL_AVATAR_ICONS`), by its component name.
+ *
+ * Nothing else is an avatar: a bare name, an unknown prefix, an icon outside
+ * the set or an emoji that is not one is refused, in a sentence.
+ *
+ * @module components/avatars/avatarChoice
+ */
+/** The prefix of an emoji avatar. */
+export declare const AVATAR_EMOJI_PREFIX = "emoji:";
+/** The prefix of an avatar drawn from `@datalayer/icons-react`. */
+export declare const AVATAR_ICON_PREFIX = "@datalayer/icons-react:";
+/** What an avatar is: an emoji, or an icon of the set by name. */
+export type AvatarChoice = {
+    kind: 'emoji';
+    emoji: string;
+} | {
+    kind: 'icon';
+    name: string;
+};
+/** Why a value is not an avatar, in a sentence. */
+export declare class AvatarRefused extends Error {
+    constructor(message: string);
+}
+/**
+ * The avatar a value names.
+ *
+ * `icons` is the set an icon must belong to (the names of
+ * `PRINCIPAL_AVATAR_ICONS`); throws `AvatarRefused` for anything else.
+ */
+export declare function parseAvatar(value: string, icons: ReadonlySet<string>): AvatarChoice;
+/** The value an avatar is kept as. */
+export declare function avatarValue(choice: AvatarChoice): string;
+/** An emoji, as an avatar value. */
+export declare const emojiAvatar: (emoji: string) => string;
+/** An icon of the set, by its component name, as an avatar value. */
+export declare const iconAvatar: (name: string) => string;