@dxos/echo 0.8.4-main.ef1bc66f44 → 0.8.4-main.effb148878

package/src/internal/{annotations → Annotation}/annotations.ts

@@ -7,14 +7,13 @@ import * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 
-import { raise } from '@dxos/debug';
 import { type JsonPath, getField } from '@dxos/effect';
 import { assertArgument, invariant } from '@dxos/invariant';
-import { DXN } from '@dxos/keys';
+import { DXN, URI } from '@dxos/keys';
 import { type Primitive } from '@dxos/util';
 
-import { type AnyProperties, EntityKind, TypeId, getSchema } from '../types';
-
+import { type Mutable } from '../common/proxy';
+import { type AnyProperties, EntityKind, TypeId, getSchema } from '../common/types';
 import { type AnnotationHelper, createAnnotationHelper } from './util';
 
 /**
@@ -46,39 +45,27 @@ export const getTypeIdentifierAnnotation = (schema: Schema.Schema.All) =>
   )(schema.ast);
 
 /**
- * @returns DXN of the schema.
+ * @returns The schema's type identifier URI — whichever URI fits.
+ *
+ * - Stored (dynamic) schemas: the schema-as-object's EchoURI, so loaded objects ride
+ *   along with their schema as a strong dependency.
+ * - Non-stored (static) schemas: the typename DXN built from `TypeAnnotation`.
  *
- * For non-stored schema returns `dxn:type:`.
- * For stored schema returns `dxn:echo:`.
+ * This URI is what gets written to an object's `system.type`; queries that filter by
+ * type also use it (see `Filter.type` / `getTypeURIFromSpecifier`), so both sides
+ * stay symmetric without per-schema branching.
  */
-export const getSchemaDXN = (schema: Schema.Schema.All): DXN | undefined => {
+export const getSchemaURI = (schema: Schema.Schema.All): URI.URI | undefined => {
   assertArgument(Schema.isSchema(schema), 'schema', 'invalid schema');
   const id = getTypeIdentifierAnnotation(schema);
   if (id) {
-    return DXN.parse(id);
+    return URI.make(id);
   }
-
-  // TODO(dmaretskyi): Add support for dynamic schema.
   const objectAnnotation = getTypeAnnotation(schema);
-  if (!objectAnnotation) {
-    return undefined;
-  }
-
-  return DXN.fromTypenameAndVersion(objectAnnotation.typename, objectAnnotation.version);
-};
-
-/**
- * @param input schema or a typename string.
- * @return type DXN.
- */
-export const getTypeDXNFromSpecifier = (input: Schema.Schema.All | string): DXN => {
-  if (Schema.isSchema(input)) {
-    return getSchemaDXN(input) ?? raise(new TypeError('Schema has no DXN'));
-  } else {
-    assertArgument(typeof input === 'string', 'input');
-    assertArgument(!input.startsWith('dxn:'), 'input');
-    return DXN.fromTypename(input);
+  if (objectAnnotation) {
+    return DXN.make(objectAnnotation.typename, objectAnnotation.version);
   }
+  return undefined;
 };
 
 //
@@ -87,16 +74,17 @@ export const getTypeDXNFromSpecifier = (input: Schema.Schema.All | string): DXN
 
 /**
  * Fully qualified globally unique typename.
- * Example: `dxos.org/type/Message`
- */
-// TODO(burdon): Reconcile with short DXN format.
-// TODO(burdon): Change "/type" => "/schema" throughout.
-export const TypenameSchema = Schema.String.pipe(Schema.pattern(/^[a-zA-Z]\w+\.[a-zA-Z]\w{1,}\/[\w/_-]+$/)).annotations(
-  {
-    description: 'Fully qualified globally unique typename',
-    example: 'dxos.org/type/Message',
-  },
-);
+ * Example: `org.dxos.type.message`
+ */
+// TODO(wittjosiah): Factor out to DXN spec.
+export const TypenameSchema = Schema.String.pipe(
+  Schema.pattern(
+    /^[a-zA-Z]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+(\.[a-zA-Z]([a-zA-Z0-9]{0,62})?)$/,
+  ),
+).annotations({
+  description: 'Fully qualified globally unique typename in reverse-DNS form.',
+  example: 'org.dxos.type.message',
+});
 
 /**
  * Semantic version format: `major.minor.patch`
@@ -175,7 +163,7 @@ export const getSchemaVersion = (schema: Schema.Schema.All): string | undefined
 /**
  * Gets the typename of the object without the version.
  * Returns only the name portion, not the DXN.
- * @example "example.org/type/Contact"
+ * @example "org.example.type.contact"
  *
  * @internal (use Obj.getTypename)
  */
@@ -185,8 +173,15 @@ export const getTypename = (obj: AnyProperties): string | undefined => {
     // Try to extract typename from DXN.
     return getSchemaTypename(schema);
   } else {
-    const type = getTypeDXN(obj);
-    return type?.asTypeDXN()?.type;
+    // `obj` may be an arbitrary value (e.g. from `isInstanceOf`); read TypeId
+    // directly so we return undefined for non-entities instead of throwing.
+    const type = (obj as any)?.[TypeId];
+    // Parse the URI string to extract typename.
+    if (DXN.isDXN(type)) {
+      const parsed = DXN.tryMake(type);
+      return parsed && DXN.getName(parsed);
+    }
+    return undefined;
   }
 };
 
@@ -194,8 +189,8 @@ export const getTypename = (obj: AnyProperties): string | undefined => {
  * @internal (use Type.setTypename)
  */
 // TODO(dmaretskyi): Rename setTypeDXN.
-export const setTypename = (obj: any, typename: DXN): void => {
-  invariant(typename instanceof DXN, 'Invalid type.');
+export const setTypename = (obj: any, typename: URI.URI): void => {
+  invariant(typeof typename === 'string', 'Invalid type.');
   Object.defineProperty(obj, TypeId, {
     value: typename,
     writable: false,
@@ -205,68 +200,25 @@ export const setTypename = (obj: any, typename: DXN): void => {
 };
 
 /**
- * @returns Object type as {@link DXN}.
- * @returns undefined if the object doesn't have a type.
- * @example `dxn:example.com/type/Person:1.0.0`
+ * @returns Object type URI — either a typename {@link DXN} or an `echo:` reference to a stored Schema object.
+ * @returns undefined if the object has no registered type URI (e.g. unresolved query result).
+ * @example `dxn:com.example.type.person:1.0.0`
+ * @example `echo:/01KKKG2FHWCMTR0BY00GJSVT1X` (stored schema)
  *
- * @internal (use Obj.getTypeDXN)
+ * @internal (use Obj.getTypeURI)
  */
-// TODO(burdon): Narrow type.
-export const getTypeDXN = (obj: AnyProperties): DXN | undefined => {
-  if (!obj) {
+export const getTypeURI = (obj: AnyProperties): URI.URI | undefined => {
+  if (obj == null) {
     return undefined;
   }
-
   const type = (obj as any)[TypeId];
-  if (!type) {
+  if (type == null) {
     return undefined;
   }
-
-  invariant(type instanceof DXN, 'Invalid object.');
+  invariant(URI.isURI(type), 'Invalid object.');
   return type;
 };
 
-/**
- * Checks if the object is an instance of the schema.
- * Only typename is compared, the schema version is ignored.
- *
- * The following cases are considered to mean that the object is an instance of the schema:
- *  - Object was created with this exact schema.
- *  - Object was created with a different version of this schema.
- *  - Object was created with a different schema (maybe dynamic) that has the same typename.
- */
-// TODO(burdon): Can we use `Schema.is`?
-export const isInstanceOf = <Schema extends Schema.Schema.AnyNoContext>(
-  schema: Schema,
-  object: any,
-): object is Schema.Schema.Type<Schema> => {
-  if (object == null) {
-    return false;
-  }
-
-  const schemaDXN = getSchemaDXN(schema);
-  if (!schemaDXN) {
-    throw new Error('Schema must have an object annotation.');
-  }
-
-  const type = getTypeDXN(object);
-  if (type && DXN.equals(type, schemaDXN)) {
-    return true;
-  }
-
-  const typename = getTypename(object);
-  if (!typename) {
-    return false;
-  }
-
-  const typeDXN = schemaDXN.asTypeDXN();
-  if (!typeDXN) {
-    return false;
-  }
-
-  return typeDXN.type === typename;
-};
-
 //
 // PropertyMeta
 //
@@ -285,6 +237,12 @@ export type PropertyMetaAnnotation = {
 
 // TODO(wittjosiah): Align with other annotations.
 // TODO(wittjosiah): Why is this separate from FormatAnnotation?
+/**
+ * Apply property-level metadata to an Effect schema. Only accepts
+ * `Schema.Schema.Any` — apply BEFORE wrapping the schema with
+ * `Type.makeObject` / `Type.makeRelation`. To read property meta off a
+ * `Type.Type` entity, unwrap it first with `Type.getSchema(entity)`.
+ */
 export const PropertyMeta = (name: string, value: PropertyMetaValue) => {
   return <A, I, R>(self: Schema.Schema<A, I, R>): Schema.Schema<A, I, R> => {
     const existingMeta = self.ast.annotations[PropertyMetaAnnotationId] as PropertyMetaAnnotation;
@@ -337,6 +295,7 @@ export const LabelAnnotation = createAnnotationHelper<string[]>(LabelAnnotationI
 /**
  * Returns the label for a given object based on {@link LabelAnnotationId}.
  * Lower-level version that requires explicit schema parameter.
+ * Skips empty strings and whitespace-only strings, continuing to the next field.
  */
 // TODO(burdon): Convert to JsonPath?
 export const getLabelWithSchema = <S extends Schema.Schema.Any>(
@@ -352,7 +311,13 @@ export const getLabelWithSchema = <S extends Schema.Schema.Any>(
     );
     const value = getField(object, accessor as JsonPath);
     switch (typeof value) {
-      case 'string':
+      case 'string': {
+        const trimmed = value.trim();
+        if (trimmed.length > 0) {
+          return value;
+        }
+        continue;
+      }
       case 'number':
       case 'boolean':
       case 'bigint':
@@ -435,7 +400,6 @@ export const setDescriptionWithSchema = <S extends Schema.Schema.Any>(
  * Identifies if a property should be included in a form or not.
  * By default, all properties are included in forms, so this is opt-out.
  */
-// TODO(burdon): UI concern.
 export const FormInputAnnotationId = Symbol.for('@dxos/schema/annotation/FormInput');
 export const FormInputAnnotation = createAnnotationHelper<boolean>(FormInputAnnotationId);
 
@@ -467,14 +431,14 @@ interface MakeAnnoationsProps<T> {
 // TODO(wittjosiah): Comment.
 export const makeUserAnnotation = <T>(props: MakeAnnoationsProps<T>): AnnotationHelper<T> => {
   assertArgument(
-    /[a-zA-Z0-9]+\.[a-zA-Z.]+\/[a-zA-Z/]+/.test(props.id),
+    /^[a-z][a-z0-9]*(\.[a-z][a-z0-9-]*){2,}$/.test(props.id),
     'id',
-    'Annotation id must be in the FQN format (dxos.org/annotation/Example).',
+    'Annotation id must be in the FQN format (org.dxos.annotation.example).',
   );
 
   const getFromAst = (ast: SchemaAST.AST) =>
     SchemaAST.getAnnotation<PropertyMetaAnnotation>(PropertyMetaAnnotationId)(ast).pipe(
-      Option.map((meta) => meta[props.id] as unknown),
+      Option.flatMap((meta) => Option.fromNullable(meta[props.id])),
       Option.map(Schema.decodeUnknownSync(props.schema)),
     );
 
@@ -485,3 +449,119 @@ export const makeUserAnnotation = <T>(props: MakeAnnoationsProps<T>): Annotation
       PropertyMeta(props.id, Schema.encodeSync(props.schema)(value)) as <S extends Schema.Schema.Any>(schema: S) => S,
   };
 };
+
+const IconAnnotationSchema = Schema.Struct({
+  /**
+   * Phosphor icon name (e.g., 'ph--user--regular', 'ph--cube--regular', 'ph--link--regular ', etc.)
+   */
+  icon: Schema.String.pipe(Schema.pattern(/^ph--[a-z-]+--[a-z]+$/)),
+
+  /**
+   * Color name.
+   *
+   * List of colors:
+   *  - 'red'
+   *  - 'orange'
+   *  - 'amber'
+   *  - 'yellow'
+   *  - 'lime'
+   *  - 'green'
+   *  - 'emerald'
+   *  - 'teal'
+   *  - 'cyan'
+   *  - 'violet'
+   *  - 'purple'
+   *  - 'fuchsia'
+   *  - 'pink'
+   *  - 'rose'
+   */
+  hue: Schema.optional(Schema.String),
+});
+
+export interface IconAnnotation extends Schema.Schema.Type<typeof IconAnnotationSchema> {}
+
+/**
+ * Icon to render in the UI.
+ */
+export const IconAnnotation = makeUserAnnotation<IconAnnotation>({
+  id: 'org.dxos.annotation.icon',
+  schema: IconAnnotationSchema,
+});
+
+/**
+ * Indicates that this entity's icon should be resolved from a property whose value is a `Ref`
+ * to another entity. Consumers (e.g. graph node builders) resolve the ref target and use that
+ * target's schema `IconAnnotation` in place of the static one declared on this schema.
+ *
+ * Useful for wrapper schemas that delegate their visual identity to a referenced sub-entity
+ * (e.g. a generic `Game` whose icon should come from its `variant` ref's typed state).
+ */
+export const IconFromRefAnnotation = makeUserAnnotation<string>({
+  id: 'org.dxos.annotation.icon.from-ref',
+  schema: Schema.String,
+});
+
+/**
+ * Options for {@link getLabel}.
+ */
+export type GetLabelOptions = {
+  /**
+   * Strategy for deriving a label when the entity has no `LabelAnnotation` value.
+   * - `'typename'`: use the entity's typename (e.g. `org.dxos.type.table`).
+   *   Useful for Card.Title chrome that must always display something, even
+   *   for unlabeled objects.
+   */
+  fallback?: 'typename';
+};
+
+/**
+ * Get the label of an entity.
+ * Accepts both reactive entities and snapshots.
+ *
+ * If `options.fallback === 'typename'` and no label is set, returns the
+ * entity's typename instead.
+ */
+export const getLabel = (entity: AnyProperties, options?: GetLabelOptions): string | undefined => {
+  const schema = getSchema(entity);
+  const label = schema != null ? getLabelWithSchema(schema, entity) : undefined;
+  if (label != null) {
+    return label;
+  }
+  if (options?.fallback === 'typename') {
+    return getTypename(entity);
+  }
+  return undefined;
+};
+
+/**
+ * Set the label of an entity.
+ * Must be called within an Obj.update or Relation.update callback.
+ */
+export const setLabel = (entity: Mutable<AnyProperties>, label: string) => {
+  const schema = getSchema(entity);
+  if (schema != null) {
+    setLabelWithSchema(schema, entity, label);
+  }
+};
+
+/**
+ * Get the description of an entity.
+ * Accepts both reactive entities and snapshots.
+ */
+export const getDescription = (entity: AnyProperties): string | undefined => {
+  const schema = getSchema(entity);
+  if (schema != null) {
+    return getDescriptionWithSchema(schema, entity);
+  }
+};
+
+/**
+ * Set the description of an entity.
+ * Must be called within an Obj.update or Relation.update callback.
+ */
+export const setDescription = (entity: Mutable<AnyProperties>, description: string) => {
+  const schema = getSchema(entity);
+  if (schema != null) {
+    setDescriptionWithSchema(schema, entity, description);
+  }
+};

package/src/internal/{annotations → Annotation}/index.ts

@@ -3,4 +3,5 @@
 //
 
 export * from './annotations';
+export * from './sorting';
 export * from './util';

package/src/internal/{api → Annotation}/sorting.ts

@@ -2,10 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
-import { getTypename } from '../annotations';
-import type { AnyEntity } from '../types';
-
-import { getLabel } from './annotations';
+import type { AnyEntity } from '../common/types';
+import { getLabel, getTypename } from './annotations';
 
 /**
  * String comparison helper for sorting.

package/src/internal/{annotations → Annotation}/util.ts

@@ -2,18 +2,23 @@
 // Copyright 2025 DXOS.org
 //
 
-import type * as Option from 'effect/Option';
+import * as Option from 'effect/Option';
 import type * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 
 import { assertArgument } from '@dxos/invariant';
 import { DXN } from '@dxos/keys';
 
-import { EntityKind } from '../types';
+import { EntityKind } from '../common/types';
 
 export interface AnnotationHelper<T> {
   /**
-   * Get the annotation value from the schema.
+   * Get the annotation value from an Effect schema.
+   *
+   * Only accepts `Schema.Schema.Any` — to read an annotation off a `Type.Type`
+   * entity, unwrap it first with `Type.getSchema(entity)`. This keeps the
+   * annotation pipeline single-shaped and forces annotations to live on the
+   * source schema, not on the post-construction Type entity.
    */
   get: (schema: Schema.Schema.Any) => Option.Option<T>;
   /**
@@ -21,7 +26,11 @@ export interface AnnotationHelper<T> {
    */
   getFromAst: (ast: SchemaAST.AST) => Option.Option<T>;
   /**
-   * Set the annotation value on the schema.
+   * Set the annotation on an Effect schema.
+   *
+   * Only accepts `Schema.Schema.Any` — annotations must be applied to the
+   * source schema BEFORE wrapping it with `Type.makeObject` / `Type.makeRelation`.
+   * In a pipe, place every `Annotation.X.set(...)` before the `Type.make...` step.
    */
   set: (value: T) => <S extends Schema.Schema.Any>(schema: S) => S;
 }
@@ -36,7 +45,7 @@ export const createAnnotationHelper = <T>(id: symbol): AnnotationHelper<T> => {
     getFromAst: (ast) => SchemaAST.getAnnotation(ast, id),
     set:
       (value) =>
-      <S extends Schema.Schema.Any>(schema: S) =>
+      <S extends Schema.Schema.Any>(schema: S): S =>
         schema.annotations({ [id]: value }) as S,
   };
 };
@@ -69,13 +78,12 @@ export const makeTypeJsonSchemaAnnotation = (options: {
   assertArgument(!!options.relationSource === (options.kind === EntityKind.Relation), 'relationSource');
   assertArgument(!!options.relationTarget === (options.kind === EntityKind.Relation), 'relationTarget');
 
-  const obj = {
-    // TODO(dmaretskyi): Should this include the version?
-    $id: options.identifier ?? DXN.fromTypename(options.typename).toString(),
+  const obj: Record<string, unknown> = {
+    $id: options.identifier ?? DXN.make(options.typename, options.version),
     entityKind: options.kind,
     version: options.version,
     typename: options.typename,
-  } as any;
+  };
   if (options.kind === EntityKind.Relation) {
     obj.relationSource = { $ref: options.relationSource };
     obj.relationTarget = { $ref: options.relationTarget };

package/src/internal/{api/entity.ts → Entity/api.ts}

@@ -3,20 +3,21 @@
 //
 
 import { invariant } from '@dxos/invariant';
-import { type DXN } from '@dxos/keys';
+import { type EchoURI } from '@dxos/keys';
 import { assumeType } from '@dxos/util';
 
-import { type InternalObjectProps, ObjectDatabaseId, getObjectDXN } from '../entities';
-import type { AnyEntity } from '../types';
+import type { AnyEntity } from '../common/types';
+import { type InternalObjectProps, ObjectDatabaseId } from './model';
+import { getObjectEchoUri } from './util';
 
 /**
- * Get the DXN of an entity.
+ * Get the canonical EchoURI of an entity.
  * Accepts both reactive entities and snapshots.
  */
-export const getDXN = (entity: AnyEntity): DXN => {
-  const dxn = getObjectDXN(entity);
-  invariant(dxn != null, 'Invalid entity.');
-  return dxn;
+export const getUri = (entity: AnyEntity): EchoURI.EchoURI => {
+  const uri = getObjectEchoUri(entity);
+  invariant(uri != null, 'Invalid entity.');
+  return uri;
 };
 
 /**