add @default decorator; uninline scalars by default

DOCS.md

···
 
 Note that `Caption` won't exist as a separate def—the abstraction is erased in the output.
 
+### Scalars
+
+TypeSpec scalars let you create named types with constraints. **By default, scalars create standalone defs** (like models):
+
+```typescript
+import "@typelex/emitter";
+
+namespace com.example {
+  model Main {
+    handle?: Handle;
+    bio?: Bio;
+  }
+
+  @maxLength(50)
+  scalar Handle extends string;
+
+  @maxLength(256)
+  @maxGraphemes(128)
+  scalar Bio extends string;
+}
+```
+
+This creates three defs: `main`, `handle`, and `bio`:
+
+```json
+{
+  "id": "com.example",
+  "defs": {
+    "main": {
+      "type": "object",
+      "properties": {
+        "handle": { "type": "ref", "ref": "#handle" },
+        "bio": { "type": "ref", "ref": "#bio" }
+      }
+    },
+    "handle": {
+      "type": "string",
+      "maxLength": 50
+    },
+    "bio": {
+      "type": "string",
+      "maxLength": 256,
+      "maxGraphemes": 128
+    }
+  }
+}
+```
+
+Use `@inline` to expand a scalar inline instead:
+
+```typescript
+import "@typelex/emitter";
+
+namespace com.example {
+  model Main {
+    handle?: Handle;
+  }
+
+  @inline
+  @maxLength(50)
+  scalar Handle extends string;
+}
+```
+
+Now `Handle` is expanded inline (no separate def):
+
+```json
+// ...
+"properties": {
+  "handle": { "type": "string", "maxLength": 50 }
+}
+// ...
+```
+
 ## Top-Level Lexicon Types
 
 TypeSpec uses `model` for almost everything. Decorators specify what kind of Lexicon type it becomes.
···
 
 ## Defaults and Constants
 
-### Defaults
+### Property Defaults
+
+You can set default values on properties:
 
 ```typescript
 import "@typelex/emitter";
···
 ```
 
 Maps to: `{"default": 1}`, `{"default": "en"}`
+
+### Type Defaults
+
+You can also set defaults on scalar and union types using the `@default` decorator:
+
+```typescript
+import "@typelex/emitter";
+
+namespace com.example {
+  model Main {
+    mode?: Mode;
+    priority?: Priority;
+  }
+
+  @default("standard")
+  scalar Mode extends string;
+
+  @default(1)
+  @closed
+  @inline
+  union Priority { 1, 2, 3 }
+}
+```
+
+This creates a default on the type definition itself:
+
+```json
+{
+  "defs": {
+    "mode": {
+      "type": "string",
+      "default": "standard"
+    }
+  }
+}
+```
+
+For unions with token references, pass the model directly:
+
+```typescript
+import "@typelex/emitter";
+
+namespace com.example {
+  model Main {
+    eventType?: EventType;
+  }
+
+  @default(InPerson)
+  union EventType { Hybrid, InPerson, Virtual, string }
+
+  @token model Hybrid {}
+  @token model InPerson {}
+  @token model Virtual {}
+}
+```
+
+This resolves to the fully-qualified token NSID:
+
+```json
+{
+  "eventType": {
+    "type": "string",
+    "knownValues": [
+      "com.example#hybrid",
+      "com.example#inPerson",
+      "com.example#virtual"
+    ],
+    "default": "com.example#inPerson"
+  }
+}
+```
+
+**Important:** When a scalar or union creates a standalone def (not `@inline`), property-level defaults must match the type's `@default`. Otherwise you'll get an error:
+
+```typescript
+@default("standard")
+scalar Mode extends string;
+
+model Main {
+  mode?: Mode = "custom";  // ERROR: Conflicting defaults!
+}
+```
+
+Solutions:
+1. Make the defaults match: `mode?: Mode = "standard"`
+2. Mark the type `@inline`: Allows property-level defaults
+3. Remove the property default: Uses the type's default
 
 ### Constants
 

packages/emitter/lib/decorators.tsp

···
 extern dec errors(target: unknown, ...errors: unknown[]);
 
 /**
+ * Forces a model, scalar, or union to be inlined instead of creating a standalone def.
+ * By default, named types create separate definitions with references.
+ * Use @inline to expand the type inline at each usage site.
+ *
+ * @example Inline model
+ * ```typespec
+ * @inline
+ * model Caption {
+ *   text?: string;
+ * }
+ *
+ * model Main {
+ *   captions?: Caption[];  // Expands inline, no separate "caption" def
+ * }
+ * ```
+ *
+ * @example Inline scalar
+ * ```typespec
+ * @inline
+ * @maxLength(50)
+ * scalar Handle extends string;
+ *
+ * model Main {
+ *   handle?: Handle;  // Expands to { type: "string", maxLength: 50 }
+ * }
+ * ```
+ *
+ * @example Inline union
+ * ```typespec
+ * @inline
+ * union Status { "active", "inactive", string }
+ *
+ * model Main {
+ *   status?: Status;  // Expands inline with knownValues
+ * }
+ * ```
+ */
+extern dec inline(target: unknown);
+
+/**
  * Specifies a default value for a scalar or union definition.
  * Only valid on standalone scalar or union defs (not @inline).
  * The value must match the underlying type (string, integer, or boolean).

packages/emitter/src/emitter.ts

···
       isClosed(this.program, unionType)
     ) {
       const propDesc = prop ? getDoc(this.program, prop) : undefined;
-      const defaultValue = prop?.defaultValue
-        ? serializeValueAsJson(this.program, prop.defaultValue, prop)
-        : undefined;
+
+      // Check for default value: property default takes precedence, then union's @default
+      let defaultValue: string | number | boolean | undefined;
+      if (prop?.defaultValue !== undefined) {
+        defaultValue = serializeValueAsJson(this.program, prop.defaultValue, prop) as any;
+      } else {
+        // If no property default, check union's @default decorator
+        const rawUnionDefault = getDefault(this.program, unionType);
+        const unionDefault = this.processDefaultValue(rawUnionDefault);
+        if (unionDefault !== undefined && typeof unionDefault === 'number') {
+          defaultValue = unionDefault;
+        }
+      }
+
       return {
         type: "integer",
         enum: variants.numericLiterals,
···
     ) {
       const isClosedUnion = isClosed(this.program, unionType);
       const propDesc = prop ? getDoc(this.program, prop) : undefined;
-      const defaultValue = prop?.defaultValue
-        ? serializeValueAsJson(this.program, prop.defaultValue, prop)
-        : undefined;
+
+      // Check for default value: property default takes precedence, then union's @default
+      let defaultValue: string | number | boolean | undefined;
+      if (prop?.defaultValue !== undefined) {
+        defaultValue = serializeValueAsJson(this.program, prop.defaultValue, prop) as any;
+      } else {
+        // If no property default, check union's @default decorator
+        const rawUnionDefault = getDefault(this.program, unionType);
+        const unionDefault = this.processDefaultValue(rawUnionDefault);
+
+        if (unionDefault !== undefined) {
+          // Check if it's a Type (model reference for tokens)
+          if (typeof unionDefault === 'object' && 'kind' in unionDefault && unionDefault.kind === 'Model') {
+            // Resolve the model reference to its NSID
+            const tokenModel = unionDefault as Model;
+            const tokenRef = this.getModelReference(tokenModel, true); // fullyQualified=true
+            if (tokenRef) {
+              defaultValue = tokenRef;
+            }
+          } else if (typeof unionDefault === 'string') {
+            defaultValue = unionDefault;
+          }
+        }
+      }
+
       const maxLength = getMaxLength(this.program, unionType);
       const minLength = getMinLength(this.program, unionType);
       const maxGraphemes = getMaxGraphemes(this.program, unionType);

packages/emitter/test/integration/lexicon-examples/input/community/lexicon/calendar/event.tsp

···
+import "@typelex/emitter";
+
+namespace community.lexicon.calendar.event {
+  /** A calendar event. */
+  @rec("tid")
+  model Main {
+    /** The name of the event. */
+    @required
+    name: string;
+
+    /** The description of the event. */
+    description?: string;
+
+    /** Client-declared timestamp when the event was created. */
+    @required
+    createdAt: datetime;
+
+    /** Client-declared timestamp when the event starts. */
+    startsAt?: datetime;
+
+    /** Client-declared timestamp when the event ends. */
+    endsAt?: datetime;
+
+    /** The attendance mode of the event. */
+    mode?: Mode;
+
+    /** The status of the event. */
+    status?: Status;
+
+    /** The locations where the event takes place. */
+    locations?: (
+      | Uri
+      | community.lexicon.location.address.Main
+      | community.lexicon.location.fsq.Main
+      | community.lexicon.location.geo.Main
+      | community.lexicon.location.hthree.Main
+    )[];
+
+    /** URIs associated with the event. */
+    uris?: Uri[];
+  }
+
+  /** The mode of the event. */
+  @default(Inperson)
+  union Mode {
+    Hybrid,
+    Inperson,
+    Virtual,
+    string,
+  }
+
+  /** A virtual event that takes place online. */
+  @token
+  model Virtual {}
+
+  /** An in-person event that takes place offline. */
+  @token
+  model Inperson {}
+
+  /** A hybrid event that takes place both online and offline. */
+  @token
+  model Hybrid {}
+
+  /** The status of the event. */
+  @default(Scheduled)
+  union Status {
+    Cancelled,
+    Planned,
+    Postponed,
+    Rescheduled,
+    Scheduled,
+    string,
+  }
+
+  /** The event has been created, but not finalized. */
+  @token
+  model Planned {}
+
+  /** The event has been created and scheduled. */
+  @token
+  model Scheduled {}
+
+  /** The event has been rescheduled. */
+  @token
+  model Rescheduled {}
+
+  /** The event has been cancelled. */
+  @token
+  model Cancelled {}
+
+  /** The event has been postponed and a new start date has not been set. */
+  @token
+  model Postponed {}
+
+  /** A URI associated with the event. */
+  model Uri {
+    @required
+    uri: uri;
+
+    /** The display name of the URI. */
+    name?: string;
+  }
+}
+
+// --- Externals ---
+
+@external
+namespace community.lexicon.location.address {
+  model Main {}
+}
+
+@external
+namespace community.lexicon.location.fsq {
+  model Main {}
+}
+
+@external
+namespace community.lexicon.location.geo {
+  model Main {}
+}
+
+@external
+namespace community.lexicon.location.hthree {
+  model Main {}
+}

packages/emitter/test/integration/lexicon-examples/input/community/lexicon/calendar/rsvp.tsp

···
+import "@typelex/emitter";
+
+namespace community.lexicon.calendar.rsvp {
+  /** An RSVP for an event. */
+  @rec("tid")
+  model Main {
+    @required
+    subject: `com`.atproto.repo.strongRef.Main;
+
+    @required
+    status: Status;
+  }
+
+  @inline
+  @default(Going)
+  union Status {
+    Interested,
+    Going,
+    Notgoing,
+    string,
+  }
+
+  /** Interested in the event */
+  @token
+  model Interested {}
+
+  /** Going to the event */
+  @token
+  model Going {}
+
+  /** Not going to the event */
+  @token
+  model Notgoing {}
+}
+
+// --- Externals ---
+
+@external
+namespace `com`.atproto.repo.strongRef {
+  model Main {}
+}

packages/emitter/test/integration/lexicon-examples/output/community/lexicon/calendar/event.json

···
     "lexicon": 1,
     "id": "community.lexicon.calendar.event",
     "defs": {
+        "main": {
+            "type": "record",
+            "description": "A calendar event.",
+            "key": "tid",
+            "record": {
+                "type": "object",
+                "required": [
+                    "name",
+                    "createdAt"
+                ],
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "description": "The name of the event."
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "The description of the event."
+                    },
+                    "createdAt": {
+                        "type": "string",
+                        "format": "datetime",
+                        "description": "Client-declared timestamp when the event was created."
+                    },
+                    "startsAt": {
+                        "type": "string",
+                        "format": "datetime",
+                        "description": "Client-declared timestamp when the event starts."
+                    },
+                    "endsAt": {
+                        "type": "string",
+                        "format": "datetime",
+                        "description": "Client-declared timestamp when the event ends."
+                    },
+                    "mode": {
+                        "type": "ref",
+                        "ref": "#mode",
+                        "description": "The attendance mode of the event."
+                    },
+                    "status": {
+                        "type": "ref",
+                        "ref": "#status",
+                        "description": "The status of the event."
+                    },
+                    "locations": {
+                        "type": "array",
+                        "description": "The locations where the event takes place.",
+                        "items": {
+                            "type": "union",
+                            "refs": [
+                                "#uri",
+                                "community.lexicon.location.address",
+                                "community.lexicon.location.fsq",
+                                "community.lexicon.location.geo",
+                                "community.lexicon.location.hthree"
+                            ]
+                        }
+                    },
+                    "uris": {
+                        "type": "array",
+                        "description": "URIs associated with the event.",
+                        "items": {
+                            "type": "ref",
+                            "ref": "#uri"
+                        }
+                    }
+                }
+            }
+        },
         "mode": {
             "type": "string",
             "description": "The mode of the event.",
···
         "hybrid": {
             "type": "token",
             "description": "A hybrid event that takes place both online and offline."
+        },
+        "status": {
+            "type": "string",
+            "description": "The status of the event.",
+            "default": "community.lexicon.calendar.event#scheduled",
+            "knownValues": [
+                "community.lexicon.calendar.event#cancelled",
+                "community.lexicon.calendar.event#planned",
+                "community.lexicon.calendar.event#postponed",
+                "community.lexicon.calendar.event#rescheduled",
+                "community.lexicon.calendar.event#scheduled"
+            ]
+        },
+        "planned": {
+            "type": "token",
+            "description": "The event has been created, but not finalized."
+        },
+        "scheduled": {
+            "type": "token",
+            "description": "The event has been created and scheduled."
+        },
+        "rescheduled": {
+            "type": "token",
+            "description": "The event has been rescheduled."
+        },
+        "cancelled": {
+            "type": "token",
+            "description": "The event has been cancelled."
+        },
+        "postponed": {
+            "type": "token",
+            "description": "The event has been postponed and a new start date has not been set."
+        },
+        "uri": {
+            "type": "object",
+            "description": "A URI associated with the event.",
+            "required": [
+                "uri"
+            ],
+            "properties": {
+                "uri": {
+                    "type": "string",
+                    "format": "uri"
+                },
+                "name": {
+                    "type": "string",
+                    "description": "The display name of the URI."
+                }
+            }
         }
     }
-}
+}

packages/emitter/test/integration/lexicon-examples/output/community/lexicon/calendar/rsvp.json

···
             "description": "Not going to the event"
         }
     }
-}
+}