# Toon — Options & Presets

`AcToonSerializerOptions` controls every Toon output behavior. Definition: `Serializers/Toons/AcToonSerializerOptions.cs`.

## Toon-specific options

| Option | Type | Default | Purpose |
|---|---|---|---|
| `Mode` | `ToonSerializationMode` | `Full` | Which sections to emit. |
| `UseMeta` | `bool` | `true` | Include `@meta`/`@types` sections. Ignored when `Mode = DataOnly`. |
| `UseIndentation` | `bool` | `true` | Pretty-print with indentation. When `false`, `=` has no surrounding spaces. |
| `IndentString` | `string` | `"  "` (2 spaces) | Indent unit when `UseIndentation = true`. |
| `UseInlineTypeHints` | `bool` | `false` | Emit `value <type>` hints in `@data` (schema already has type info). |
| `UseInlineComments` | `bool` | `false` | Emit property descriptions as inline comments. |
| `ShowCollectionCount` | `bool` | `true` | Emit `<Type[]> (count: N) ` header on arrays/dictionaries. |
| `UseMultiLineStrings` | `bool` | `true` | Triple-quote format for long strings. |
| `MultiLineStringThreshold` | `int` | `80` | Character count above which a string becomes multi-line. |
| `UseEnhancedMetadata` | `bool` | `true` | Full per-property metadata (description + purpose + constraints + examples + navigation) vs compact single-line form. |
| `OmitDefaultValues` | `bool` | `true` | Skip properties whose value equals `default(T)` / `null` / `0` / `false`. |
| `WriteTypeNames` | `bool` | `true` | Emit the type name before `{` on `@data` objects. |
| `MaxExampleStringLength` | `int` | `50` | Truncate example values in `@types` beyond this length. |

## Inherited from `AcSerializerOptions`

| Option | Type | Notes |
|---|---|---|
| `MaxDepth` | `byte` | Recursion guard; when exceeded, `null` is emitted. |
| `ReferenceHandling` | `ReferenceHandlingMode` | `None` / `OnlyId` / `All` — required for circular or shared-reference graphs. |
| `SerializerType` | `AcSerializerType` | Fixed to `Toon`. |

## `ToonSerializationMode` enum

```csharp
public enum ToonSerializationMode : byte
{
    Full     = 0,  // @meta + @types + @data (default)
    MetaOnly = 1,  // @meta + @types only
    DataOnly = 2,  // @data only
}
```

## Presets

Each preset is a fresh instance (static property with `new` expression — no shared state between retrievals).

### `Default`

```
Mode = Full, UseMeta = true, UseIndentation = true,
OmitDefaultValues = true, WriteTypeNames = true
```

First-time serialization with full context for the LLM.

### `MetaOnly`

```
Mode = MetaOnly, UseMeta = true, UseIndentation = true,
UseInlineComments = true
```

Send schema once at conversation start. `UseInlineComments = true` adds clarity since no `@data` follows.

### `DataOnly`

```
Mode = DataOnly, UseMeta = false, UseIndentation = true,
OmitDefaultValues = true, WriteTypeNames = true
```

Subsequent sends once the LLM already has the schema.

### `Compact`

```
Mode = DataOnly, UseMeta = false, UseIndentation = true,
OmitDefaultValues = true, WriteTypeNames = false,
ReferenceHandling = None
```

Data-only, no type names, no reference tracking. Note: `UseIndentation = true` here — truly token-minimal output requires manually setting `UseIndentation = false` on a custom options instance.

### `Verbose`

```
Mode = Full, UseMeta = true, UseIndentation = true,
UseInlineTypeHints = true, UseInlineComments = true,
OmitDefaultValues = false, WriteTypeNames = true
```

Debugging / documentation — every hint turned on, defaults included. Bloats tokens; avoid for production LLM contexts.

## Factory helpers

```csharp
AcToonSerializerOptions.WithMaxDepth(10)
AcToonSerializerOptions.WithoutReferenceHandling()
```

Short-hand for common one-off customizations.

## Custom options

All properties are `init;` — assemble once per serialization call:

```csharp
var opts = new AcToonSerializerOptions
{
    Mode = ToonSerializationMode.Full,
    UseIndentation = false,         // tight token-minimal output
    ShowCollectionCount = true,
    UseMultiLineStrings = false,    // keep long strings inline
    OmitDefaultValues = true,
    MaxDepth = 20
};
string toon = AcToonSerializer.Serialize(value, opts);
```

## Public API overloads

| Method | Purpose |
|---|---|
| `Serialize<T>(T value)` | Default options. |
| `Serialize<T>(T value, AcToonSerializerOptions)` | Custom options. |
| `Serialize<T>(T value, string domainDescription, AcToonSerializerOptions)` | Adds `context = "..."` line to `@meta`. |
| `SerializeTypeMetadata<T>()` / `SerializeTypeMetadata(Type)` | Schema only — uses `MetaOnly` internally. |
| `SerializeMetadata(IEnumerable<Type>)` | Schema for multiple types (no instance required). |
| `SerializeMetadata(params Type[])` | Schema for multiple types (params syntax). |
| `SerializeMetadata(string domainDescription, params Type[])` | Multi-type schema with domain context in `@meta`. |

## Picking a preset / customization

| Scenario | Choice |
|---|---|
| First prompt to an LLM in a new conversation | `Default` |
| Send schema once, many data round-trips | `MetaOnly` then `DataOnly` |
| Token-minimal streaming after schema is established | Custom: `Mode = DataOnly` + `UseIndentation = false` + `WriteTypeNames = false` |
| Debugging, local inspection | `Verbose` |
| Cyclic object graph (entity with backrefs) | Any preset, but ensure `ReferenceHandling = OnlyId` or `All` on a custom options instance |