# Render API reference

> Exports of @gramforge/render.

Source: https://gramforge.n.yatsyk.com/docs/render/jsdoc

## Functions

### entitiesForNodes

Render an arbitrary RichText node sequence to `{ text, entities }`. Internal:
shared by {@link toEntities} and the RichBlock lowering in `./richmessage`.

```ts
entitiesForNodes(nodes: readonly RichTextNode[]): EntitiesPayload
```

### toEntities

The DEFAULT renderer. Lowers a validated `MessageText`/`CaptionText` to the
Bot API `{ text, entities }` payload with UTF-16 code-unit offsets.

```ts
toEntities(message: MessageText | CaptionText): EntitiesPayload
```

### toHtml

Render a validated message/caption to Telegram's supported HTML subset.

```ts
toHtml(message: MessageText | CaptionText): string
```

### toMarkdownV2

RENDER FALLBACK ONLY — see the file header. Render a validated message/caption
to Telegram MarkdownV2 wire text with all reserved characters escaped.

```ts
toMarkdownV2(message: MessageText | CaptionText): string
```

### toRichMessage

Capability-flagged partial renderer for the Bot API 10.1 block subset. The
`capability` token is a REQUIRED parameter — omitting it is a type error.

```ts
toRichMessage(nodes: readonly RichBlockNode[], capability: RichMessageCapability): RenderRichMessageResult
```

## Types

### EntityLanguage

Presence of a `pre` block's language tag, as a DU (no `.optional()`).

```ts
type EntityLanguage = | { readonly kind: "known"; readonly value: string }
  | { readonly kind: "unknown" }
```

### MessageEntity

The Bot API `MessageEntity` union, as produced by {@link toEntities}.

```ts
type MessageEntity = SimpleEntity | PreEntity | TextLinkEntity | TextMentionEntity
```

### SimpleEntityType

Entity types that carry no extra fields beyond `offset`/`length`.

```ts
type SimpleEntityType = | "bold"
  | "italic"
  | "underline"
  | "strikethrough"
  | "code"
  | "blockquote"
  | "expandable_blockquote"
  | "spoiler"
  | "mention"
```

### LoweredBlock

```ts
type LoweredBlock = LoweredHeading | LoweredMath | LoweredTable | LoweredCollapsible
```

### RenderRichMessageResult

```ts
type RenderRichMessageResult = | { readonly kind: "ok"; readonly value: RichMessagePayload }
  | { readonly kind: "unsupported-node"; readonly nodeKind: string }
```

## Interfaces

### EntitiesPayload

The default render payload: the plain text plus its formatting entities.

```ts
interface EntitiesPayload
```

- `text: string`
- `entities: readonly MessageEntity[]`

### PreEntity

A `pre` (code block) entity, optionally carrying a language tag.

```ts
interface PreEntity
```

- `type: "pre"`
- `offset: number`
- `length: number`
- `language: EntityLanguage`

### SimpleEntity

A formatting entity with no type-specific payload.

```ts
interface SimpleEntity
```

- `type: SimpleEntityType`
- `offset: number`
- `length: number`

### TextLinkEntity

A `text_link` entity — inline text linking to `url`.

```ts
interface TextLinkEntity
```

- `type: "text_link"`
- `offset: number`
- `length: number`
- `url: string`

### TextMentionEntity

A `text_mention` entity — a mention of a user by numeric id.

```ts
interface TextMentionEntity
```

- `type: "text_mention"`
- `offset: number`
- `length: number`
- `user: { readonly id: number; }`

### LoweredCollapsible

```ts
interface LoweredCollapsible
```

- `kind: "collapsible"`
- `summary: EntitiesPayload`
- `blocks: readonly LoweredBlock[]`

### LoweredHeading

```ts
interface LoweredHeading
```

- `kind: "heading"`
- `level: 1 | 2 | 3 | 4`
- `content: EntitiesPayload`

### LoweredMath

```ts
interface LoweredMath
```

- `kind: "math"`
- `latex: string`

### LoweredTable

```ts
interface LoweredTable
```

- `kind: "table"`
- `header: readonly EntitiesPayload[]`
- `rows: readonly (readonly EntitiesPayload[])[]`

### RichMessageCapability

The capability token gating access to the 10.1 rich-message surface.

```ts
interface RichMessageCapability
```

- `kind: "rich-message-10-1"`

### RichMessagePayload

The successfully-lowered 10.1 rich message.

```ts
interface RichMessagePayload
```

- `blocks: readonly LoweredBlock[]`

## Constants

### EntitiesPayloadSchema

```ts
const EntitiesPayloadSchema: z.ZodType<EntitiesPayload, z.ZodTypeDef, EntitiesPayload>
```

### MessageEntitySchema

```ts
const MessageEntitySchema: z.ZodType<MessageEntity, z.ZodTypeDef, MessageEntity>
```