@dxos/echo 0.8.4-main.40e3dcdf1b → 0.8.4-main.43cb759274

package/src/View.ts

@@ -8,8 +8,9 @@ import * as Schema from 'effect/Schema';
 
 import { QueryAST } from '@dxos/echo-protocol';
 import { JsonPath } from '@dxos/effect';
-import { PublicKey } from '@dxos/keys';
+import { DXN, PublicKey } from '@dxos/keys';
 
+import * as Annotation from './Annotation';
 import * as Filter from './Filter';
 import * as internal from './internal';
 import * as Obj from './Obj';
@@ -74,23 +75,18 @@ const ViewSchema = Schema.Struct({
    */
   projection: Projection,
 }).pipe(
-  Type.object({
-    typename: 'org.dxos.type.view',
-    version: '0.1.0',
-  }),
-  internal.SystemTypeAnnotation.set(true),
+  internal.HiddenAnnotation.set(true),
+  Annotation.IconAnnotation.set({ icon: 'ph--funnel--regular', hue: 'green' }),
+  Type.makeObject(DXN.make('org.dxos.type.view', '0.1.0')),
 );
 
-export interface View extends Schema.Schema.Type<typeof ViewSchema> {}
-
-/**
- * View instance type.
- */
-// NOTE: This interface is explicitly defined rather than derived from the schema to avoid
-//   TypeScript "cannot be named" portability errors. The schema contains QueryAST.Query which
-//   references internal @dxos/echo-protocol module paths. Without this explicit interface,
-//   any schema using Ref.Ref(View) would inherit the non-portable type and fail to compile.
+// NOTE: Declared as a named interface and the `View` const is annotated `Type.Obj<View>` so
+//   downstream consumers see a named `View` type instead of the inlined `QueryAST.Query` union.
+//   Without the named interface, embedding `Type.getSchema(View.View)` in a downstream
+//   `Schema.Struct` triggers TS2742 portability errors (e.g. plugin-kanban, plugin-table).
 // TODO(wittjosiah): Find a better solution that doesn't require manually keeping the interface in sync.
+export interface View extends Type.InstanceType<typeof ViewSchema> {}
+
 export const View: Type.Obj<View> = ViewSchema as any;
 
 export const make = (props: Partial<Obj.MakeProps<typeof View>>): View => {

package/src/exemplars.test.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import * as Obj from './Obj';
+import { TestSchema } from './testing';
+import type * as Type from './Type';
+
+describe('Exemplars', () => {
+  test('factory', ({ expect }) => {
+    const factory = <S extends Type.AnyObj>(schema: S) => {
+      return (props: Obj.MakeProps<S>) => Obj.make(schema, props);
+    };
+
+    const makePerson = factory(TestSchema.Person);
+    const person = makePerson({ name: 'John Doe' });
+    expect(person.name).toBe('John Doe');
+  });
+});

package/src/index.ts

@@ -3,27 +3,33 @@
 //
 
 export { QueryAST } from '@dxos/echo-protocol';
-// TODO(wittjosiah): Refactor DXN to not use statics similar to Query.
-export { DXN } from '@dxos/keys';
+export { DXN, EID, URI } from '@dxos/keys';
 
 export * as Annotation from './Annotation';
 export * as Database from './Database';
 export * as Entity from './Entity';
+// TODO(burdon): Rename to Error (less problematic than Obj/Object).
 export * as Err from './Err';
 export * as Feed from './Feed';
 export * as Filter from './Filter';
 export * as Format from './Format';
 export * as Hypergraph from './Hypergraph';
+export * as Json from './Json';
 export * as JsonSchema from './JsonSchema';
 export * as Key from './Key';
+export * as Migration from './Migration';
 export * as Obj from './Obj';
 export * as Order from './Order';
 export * as Query from './Query';
 export * as QueryResult from './QueryResult';
 export * as Ref from './Ref';
+export * as Registry from './Registry';
 export * as Relation from './Relation';
-export * as SchemaRegistry from './SchemaRegistry';
+export * as Scope from './Scope';
+export * as StateMap from './StateMap';
 export * as Tag from './Tag';
+export * as TagIndex from './TagIndex';
+export * as Tagging from './Tagging';
 export * as Type from './Type';
 export * as Collection from './Collection';
 export * as View from './View';

package/src/internal/Annotation/annotations.test.ts

@@ -5,9 +5,13 @@
 import * as Schema from 'effect/Schema';
 import { describe, test } from 'vitest';
 
-import { EchoObjectSchema } from '../Entity';
+import { DXN } from '@dxos/keys';
 
-import { LabelAnnotation, TypenameSchema, VersionSchema, getLabelWithSchema } from './annotations';
+import { createEchoSchema } from '../../testing';
+import * as Type from '../../Type';
+import { EntityKind } from '../common/types';
+import { EchoObjectSchema } from '../Entity';
+import { LabelAnnotation, TypenameSchema, VersionSchema, getLabelWithSchema, getTypeAnnotation } from './annotations';
 
 // TODO(dmaretskyi): Use one of the testing schemas.
 const TestObject = Schema.Struct({
@@ -18,21 +22,16 @@ const TestObject = Schema.Struct({
 
 type TestObject = Schema.Schema.Type<typeof TestObject>;
 
-const TestEchoSchema = TestObject.pipe(
-  EchoObjectSchema({
-    typename: 'org.dxos.type.test',
-    version: '0.1.0',
-  }),
-);
+const TestEchoSchema = TestObject.pipe(EchoObjectSchema(DXN.make('org.dxos.type.test', '0.1.0')));
 
-type TestEchoSchema = Schema.Schema.Type<typeof TestEchoSchema>;
+type TestEchoSchema = Type.InstanceType<typeof TestEchoSchema>;
 
 describe('annotations', () => {
   describe('Typename', () => {
     test('should validate typename', ({ expect }) => {
       // Valid (reverse-DNS format).
       expect(TypenameSchema.make('org.dxos.type.foo')).to.exist;
-      expect(TypenameSchema.make('org.dxos.type.foo-bar')).to.exist;
+      expect(TypenameSchema.make('org.dxos.type.fooBar')).to.exist;
       expect(TypenameSchema.make('org.dxos.type.foobar')).to.exist;
 
       // Invalid.
@@ -82,15 +81,85 @@ describe('annotations', () => {
       expect(getLabelWithSchema(TestObject, obj)).toBeUndefined();
     });
 
+    test('should skip empty string and fallback to next path', ({ expect }) => {
+      const obj: TestObject = {
+        name: '',
+        fallbackName: 'Fallback Name',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toEqual('Fallback Name');
+    });
+
+    test('should skip whitespace-only string and fallback to next path', ({ expect }) => {
+      const obj: TestObject = {
+        name: '   ',
+        fallbackName: 'Fallback Name',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toEqual('Fallback Name');
+    });
+
+    test('should return undefined if all paths are empty strings', ({ expect }) => {
+      const obj: TestObject = {
+        name: '',
+        fallbackName: '',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toBeUndefined();
+    });
+
+    test('should return undefined if all paths are whitespace-only', ({ expect }) => {
+      const obj: TestObject = {
+        name: '  ',
+        fallbackName: '\t\n',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toBeUndefined();
+    });
+
+    test('should preserve original string with leading/trailing whitespace when valid', ({ expect }) => {
+      const obj: TestObject = {
+        name: '  Valid Name  ',
+        fallbackName: 'Fallback Name',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toEqual('  Valid Name  ');
+    });
+
     test('should return label from echo object', ({ expect }) => {
-      const obj: TestEchoSchema = {
+      const obj = {
         id: 'test',
         name: 'Primary Name',
         fallbackName: 'Fallback Name',
         other: 'Other',
-      };
+      } as unknown as TestEchoSchema;
+
+      expect(getLabelWithSchema(Type.getSchema(TestEchoSchema), obj)).toEqual('Primary Name');
+    });
+  });
+
+  // `getTypeAnnotation` reads annotations from an Effect Schema. To read off a
+  // `Type.Type` entity (static or persisted), unwrap with `Type.getSchema(entity)`
+  // first — that handles both the static `StaticTypeSchemaSlot` case and the
+  // persisted `jsonSchema` rebuild case.
+  describe('getTypeAnnotation via Type.getSchema(entity)', () => {
+    test('returns TypeAnnotation for a static Type.Obj entity', ({ expect }) => {
+      const annotation = getTypeAnnotation(Type.getSchema(TestEchoSchema));
+      expect(annotation).toBeDefined();
+      expect(annotation?.kind).toBe(EntityKind.Object);
+      expect(annotation?.typename).toBe('org.dxos.type.test');
+    });
 
-      expect(getLabelWithSchema(TestEchoSchema, obj)).toEqual('Primary Name');
+    test('returns TypeAnnotation for a persisted Type.Type entity', ({ expect }) => {
+      const persisted = createEchoSchema(Type.getSchema(TestEchoSchema));
+      const annotation = getTypeAnnotation(Type.getSchema(persisted));
+      expect(annotation).toBeDefined();
+      expect(annotation?.typename).toBe('org.dxos.type.test');
     });
   });
 });

package/src/internal/Annotation/annotations.ts

@@ -7,16 +7,17 @@ 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 * as Annotation from '../../Annotation';
 import { type Mutable } from '../common/proxy';
 import { type AnyProperties, EntityKind, TypeId, getSchema } from '../common/types';
+import { createAnnotationHelper } from './util';
 
-import { type AnnotationHelper, createAnnotationHelper } from './util';
+const ANNOTATION_TYPE_ID: Annotation.TypeId = '~@dxos/echo/Annotation' as const;
 
 /**
  * @internal
@@ -47,39 +48,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.
  *
- * For non-stored schema returns `dxn:type:`.
- * For stored schema returns `dxn:echo:`.
+ * - Stored (dynamic) schemas: the schema-as-object's EID, so loaded objects ride
+ *   along with their schema as a strong dependency.
+ * - Non-stored (static) schemas: the typename DXN built from `TypeAnnotation`.
+ *
+ * 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;
 };
 
 //
@@ -90,14 +79,15 @@ export const getTypeDXNFromSpecifier = (input: Schema.Schema.All | string): DXN
  * Fully qualified globally unique typename.
  * Example: `org.dxos.type.message`
  */
-// TODO(burdon): Reconcile with short DXN format.
-// TODO(burdon): Change "type" => "schema" throughout.
-export const TypenameSchema = Schema.String.pipe(Schema.pattern(/^[a-z][a-z0-9]*(\.[a-z][a-z0-9-]*){2,}$/)).annotations(
-  {
-    description: 'Fully qualified globally unique typename in lowercase reverse-DNS form.',
-    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`
@@ -186,8 +176,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;
   }
 };
 
@@ -195,8 +192,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 => {
+  assertArgument(typeof typename === 'string', 'typename', 'Invalid type.');
   Object.defineProperty(obj, TypeId, {
     value: typename,
     writable: false,
@@ -206,68 +203,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.
+ * @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
 //
@@ -286,6 +240,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;
@@ -323,10 +283,10 @@ export const SchemaMetaSymbol = Symbol.for('@dxos/schema/SchemaMeta');
 export type SchemaMeta = TypeMeta & { id: string };
 
 /**
- * Identifies a schema as a schema for a hidden system type.
+ * Identifies a schema as hidden from user-facing surfaces (like dotfiles — visible only via an advanced setting).
  */
-export const SystemTypeAnnotationId = Symbol.for('@dxos/schema/annotation/SystemType');
-export const SystemTypeAnnotation = createAnnotationHelper<boolean>(SystemTypeAnnotationId);
+export const HiddenAnnotationId = Symbol.for('@dxos/schema/annotation/Hidden');
+export const HiddenAnnotation = createAnnotationHelper<boolean>(HiddenAnnotationId);
 
 /**
  * Identifies label property or JSON path expression.
@@ -338,6 +298,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>(
@@ -353,7 +314,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':
@@ -436,10 +403,16 @@ 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);
 
+/**
+ * When set on a `Ref` property, the form renders the referenced object's own
+ * fields inline (a nested form bound to the target) instead of a picker.
+ */
+export const FormInlineAnnotationId = Symbol.for('@dxos/schema/annotation/FormInline');
+export const FormInlineAnnotation = createAnnotationHelper<boolean>(FormInlineAnnotationId);
+
 /**
  * Default field to be used on referenced schema to lookup the value.
  */
@@ -465,26 +438,29 @@ interface MakeAnnoationsProps<T> {
   schema: Schema.Schema<T, any, never>;
 }
 
-// TODO(wittjosiah): Comment.
-export const makeUserAnnotation = <T>(props: MakeAnnoationsProps<T>): AnnotationHelper<T> => {
+// Annotation ids use the same NSID / reverse-DNS format as TypenameSchema —
+// dot-separated segments, middle segments may be hyphenated, final segment may be camelCase.
+// At least 3 segments are required (e.g. org.dxos.annotation.example).
+export const makeUserAnnotation = <T>(props: MakeAnnoationsProps<T>): Annotation.Annotation<T> => {
   assertArgument(
-    /^[a-z][a-z0-9]*(\.[a-z][a-z0-9-]*){2,}$/.test(props.id),
+    /^[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])?){2,}(\.[a-zA-Z]([a-zA-Z0-9]{0,62})?)?$/.test(
+      props.id,
+    ),
     'id',
-    'Annotation id must be in the FQN format (org.dxos.annotation.example).',
+    'Annotation id must be in the FQN format (org.dxos.annotation.example or org.dxos.space.rootCollection).',
   );
 
-  const getFromAst = (ast: SchemaAST.AST) =>
-    SchemaAST.getAnnotation<PropertyMetaAnnotation>(PropertyMetaAnnotationId)(ast).pipe(
-      Option.map((meta) => meta[props.id] as unknown),
-      Option.map(Schema.decodeUnknownSync(props.schema)),
-    );
-
-  return {
-    get: (schema) => getFromAst(schema.ast),
-    getFromAst: (ast) => getFromAst(ast),
+  const annotation: Annotation.Annotation<T> = {
+    [ANNOTATION_TYPE_ID]: { _Type: {} as T },
+    key: props.id as Annotation.Key,
+    schema: props.schema,
+    get: (schema) => getFromAst(schema.ast, annotation),
+    getFromAst: (ast) => getFromAst(ast, annotation),
     set: (value) =>
       PropertyMeta(props.id, Schema.encodeSync(props.schema)(value)) as <S extends Schema.Schema.Any>(schema: S) => S,
   };
+
+  return annotation;
 };
 
 const IconAnnotationSchema = Schema.Struct({
@@ -512,7 +488,6 @@ const IconAnnotationSchema = Schema.Struct({
    *  - 'pink'
    *  - 'rose'
    */
-
   hue: Schema.optional(Schema.String),
 });
 
@@ -526,20 +501,54 @@ export const IconAnnotation = makeUserAnnotation<IconAnnotation>({
   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): string | undefined => {
+export const getLabel = (entity: AnyProperties, options?: GetLabelOptions): string | undefined => {
   const schema = getSchema(entity);
-  if (schema != null) {
-    return getLabelWithSchema(schema, 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.change or Relation.change callback.
+ * Must be called within an Obj.update or Relation.update callback.
  */
 export const setLabel = (entity: Mutable<AnyProperties>, label: string) => {
   const schema = getSchema(entity);
@@ -559,9 +568,29 @@ export const getDescription = (entity: AnyProperties): string | undefined => {
   }
 };
 
+/**
+ * Get the icon annotation for an entity, resolved via its type-level `IconAnnotation`.
+ * Accepts both reactive entities and snapshots.
+ *
+ * Returns the full `{ icon, hue }` annotation so callers can use both the phosphor icon
+ * name and the suggested colour. Callers wanting just the icon name typically write
+ * `Obj.getIcon(obj)?.icon ?? 'ph--cube--regular'`.
+ *
+ * Note: this is the "static" icon from the object's own schema. It does not follow
+ * `IconFromRefAnnotation` delegation — call sites needing that (e.g. app-graph node
+ * builders) should resolve the ref themselves.
+ */
+export const getIcon = (entity: AnyProperties): IconAnnotation | undefined => {
+  const schema = getSchema(entity);
+  if (schema == null) {
+    return undefined;
+  }
+  return Option.getOrUndefined(IconAnnotation.get(schema));
+};
+
 /**
  * Set the description of an entity.
- * Must be called within an Obj.change or Relation.change callback.
+ * Must be called within an Obj.update or Relation.update callback.
  */
 export const setDescription = (entity: Mutable<AnyProperties>, description: string) => {
   const schema = getSchema(entity);
@@ -569,3 +598,12 @@ export const setDescription = (entity: Mutable<AnyProperties>, description: stri
     setDescriptionWithSchema(schema, entity, description);
   }
 };
+
+export { Dictionary, Key, getDictionary, setDictionary } from './dictionary';
+
+export const getFromAst = <T>(ast: SchemaAST.AST, annotation: Annotation.Annotation<T>): Option.Option<T> => {
+  return SchemaAST.getAnnotation<PropertyMetaAnnotation>(PropertyMetaAnnotationId)(ast).pipe(
+    Option.flatMap((meta) => Option.fromNullable(meta[annotation.key])),
+    Option.map(Schema.decodeUnknownSync(annotation.schema)),
+  );
+};