Interface DrawlistBuilderV2

ZRDL v2 drawlist builder interface.

Extends v1 with SET_CURSOR command for native cursor control. When v2 is negotiated, the engine handles cursor display internally, eliminating the need for "fake cursor" glyphs.

interface DrawlistBuilderV2 {
    addBlob(bytes: Uint8Array): number | null;
    addTextRunBlob(
        segments: readonly Readonly<
            {
                style?: Readonly<
                    {
                        bg?: Readonly<{ b: number; g: number; r: number }>;
                        bold?: boolean;
                        dim?: boolean;
                        fg?: Readonly<{ b: number; g: number; r: number }>;
                        inverse?: boolean;
                        italic?: boolean;
                        underline?: boolean;
                    },
                >;
                text: string;
            },
        >[],
    ): number
    | null;
    build(): DrawlistBuildResult;
    clear(): void;
    clearTo(
        cols: number,
        rows: number,
        style?: Readonly<
            {
                bg?: Readonly<{ b: number; g: number; r: number }>;
                bold?: boolean;
                dim?: boolean;
                fg?: Readonly<{ b: number; g: number; r: number }>;
                inverse?: boolean;
                italic?: boolean;
                underline?: boolean;
            },
        >,
    ): void;
    drawText(
        x: number,
        y: number,
        text: string,
        style?: Readonly<
            {
                bg?: Readonly<{ b: number; g: number; r: number }>;
                bold?: boolean;
                dim?: boolean;
                fg?: Readonly<{ b: number; g: number; r: number }>;
                inverse?: boolean;
                italic?: boolean;
                underline?: boolean;
            },
        >,
    ): void;
    drawTextRun(x: number, y: number, blobIndex: number): void;
    fillRect(
        x: number,
        y: number,
        w: number,
        h: number,
        style?: Readonly<
            {
                bg?: Readonly<{ b: number; g: number; r: number }>;
                bold?: boolean;
                dim?: boolean;
                fg?: Readonly<{ b: number; g: number; r: number }>;
                inverse?: boolean;
                italic?: boolean;
                underline?: boolean;
            },
        >,
    ): void;
    hideCursor(): void;
    popClip(): void;
    pushClip(x: number, y: number, w: number, h: number): void;
    reset(): void;
    setCursor(state: CursorState): void;
}

Hierarchy (View Summary)

DrawlistBuilderV1
- DrawlistBuilderV2

Index

Methods

addBlob addTextRunBlob build clear clearTo drawText drawTextRun fillRect hideCursor popClip pushClip reset setCursor

Methods

addBlob

addBlob(bytes: Uint8Array): number | null
Append a blob payload to the blob table and return its index.

Notes:
- The blob span length MUST be 4-byte aligned.
- Blob content is not deduplicated; callers may cache returned indices.
Parameters
- bytes: Uint8Array
Returns number | null
Inherited from DrawlistBuilderV1.addBlob
- Defined in core/src/drawlist/types.ts:87

addTextRunBlob

addTextRunBlob(
    segments: readonly Readonly<
        {
            style?: Readonly<
                {
                    bg?: Readonly<{ b: number; g: number; r: number }>;
                    bold?: boolean;
                    dim?: boolean;
                    fg?: Readonly<{ b: number; g: number; r: number }>;
                    inverse?: boolean;
                    italic?: boolean;
                    underline?: boolean;
                },
            >;
            text: string;
        },
    >[],
): number
| null
Convenience helper that encodes a ZRDL v1 DRAW_TEXT_RUN blob payload from segments and appends it via addBlob().
Parameters
- segments: readonly Readonly<
      {
          style?: Readonly<
              {
                  bg?: Readonly<{ b: number; g: number; r: number }>;
                  bold?: boolean;
                  dim?: boolean;
                  fg?: Readonly<{ b: number; g: number; r: number }>;
                  inverse?: boolean;
                  italic?: boolean;
                  underline?: boolean;
              },
          >;
          text: string;
      },
  >[]
Returns number | null
Inherited from DrawlistBuilderV1.addTextRunBlob
- Defined in core/src/drawlist/types.ts:92

build

build(): DrawlistBuildResult
Finalize and return the ZRDL binary, or error if any command failed.

Returns DrawlistBuildResult
Inherited from DrawlistBuilderV1.build
- Defined in core/src/drawlist/types.ts:96

clear

clear(): void
Clear framebuffer. Emits OP_CLEAR (opcode 1).

Returns void
Inherited from DrawlistBuilderV1.clear
- Defined in core/src/drawlist/types.ts:63

clearTo

clearTo(
    cols: number,
    rows: number,
    style?: Readonly<
        {
            bg?: Readonly<{ b: number; g: number; r: number }>;
            bold?: boolean;
            dim?: boolean;
            fg?: Readonly<{ b: number; g: number; r: number }>;
            inverse?: boolean;
            italic?: boolean;
            underline?: boolean;
        },
    >,
): void
Clear framebuffer and fill the viewport with a style.

Why: ZRDL v1 CLEAR carries no style payload. This helper provides a deterministic "clear with background" that works in both raw and widget render modes by emitting CLEAR + FILL_RECT.
Parameters
- cols: number
- rows: number
- Optionalstyle: Readonly<
      {
          bg?: Readonly<{ b: number; g: number; r: number }>;
          bold?: boolean;
          dim?: boolean;
          fg?: Readonly<{ b: number; g: number; r: number }>;
          inverse?: boolean;
          italic?: boolean;
          underline?: boolean;
      },
  >
Returns void
Inherited from DrawlistBuilderV1.clearTo
- Defined in core/src/drawlist/types.ts:71

drawText

drawText(
    x: number,
    y: number,
    text: string,
    style?: Readonly<
        {
            bg?: Readonly<{ b: number; g: number; r: number }>;
            bold?: boolean;
            dim?: boolean;
            fg?: Readonly<{ b: number; g: number; r: number }>;
            inverse?: boolean;
            italic?: boolean;
            underline?: boolean;
        },
    >,
): void
Draw text at (x,y). Strings are interned and deduplicated. Emits OP_DRAW_TEXT (opcode 3).
Parameters
- x: number
- y: number
- text: string
- Optionalstyle: Readonly<
      {
          bg?: Readonly<{ b: number; g: number; r: number }>;
          bold?: boolean;
          dim?: boolean;
          fg?: Readonly<{ b: number; g: number; r: number }>;
          inverse?: boolean;
          italic?: boolean;
          underline?: boolean;
      },
  >
Returns void
Inherited from DrawlistBuilderV1.drawText
- Defined in core/src/drawlist/types.ts:75

drawTextRun

drawTextRun(x: number, y: number, blobIndex: number): void
Draw a pre-measured text run blob at (x,y). Emits OP_DRAW_TEXT_RUN (opcode 6).
Parameters
- x: number
- y: number
- blobIndex: number
Returns void
Inherited from DrawlistBuilderV1.drawTextRun
- Defined in core/src/drawlist/types.ts:94

fillRect

fillRect(
    x: number,
    y: number,
    w: number,
    h: number,
    style?: Readonly<
        {
            bg?: Readonly<{ b: number; g: number; r: number }>;
            bold?: boolean;
            dim?: boolean;
            fg?: Readonly<{ b: number; g: number; r: number }>;
            inverse?: boolean;
            italic?: boolean;
            underline?: boolean;
        },
    >,
): void
Fill rectangle at (x,y) with size (w,h). Emits OP_FILL_RECT (opcode 2).
Parameters
- x: number
- y: number
- w: number
- h: number
- Optionalstyle: Readonly<
      {
          bg?: Readonly<{ b: number; g: number; r: number }>;
          bold?: boolean;
          dim?: boolean;
          fg?: Readonly<{ b: number; g: number; r: number }>;
          inverse?: boolean;
          italic?: boolean;
          underline?: boolean;
      },
  >
Returns void
Inherited from DrawlistBuilderV1.fillRect
- Defined in core/src/drawlist/types.ts:73

hideCursor

hideCursor(): void
Hide the cursor by emitting SET_CURSOR with visible=false. Convenience method equivalent to setCursor({ ..., visible: false }).

Returns void
- Defined in core/src/drawlist/types.ts:146

popClip

popClip(): void
Pop clipping rectangle from clip stack. Emits OP_POP_CLIP (opcode 5).

Returns void
Inherited from DrawlistBuilderV1.popClip
- Defined in core/src/drawlist/types.ts:79

pushClip

pushClip(x: number, y: number, w: number, h: number): void
Push clipping rectangle onto clip stack. Emits OP_PUSH_CLIP (opcode 4).
Parameters
- x: number
- y: number
- w: number
- h: number
Returns void
Inherited from DrawlistBuilderV1.pushClip
- Defined in core/src/drawlist/types.ts:77

reset

reset(): void
Reset builder state for reuse. Clears commands, strings, and error state.

Returns void
Inherited from DrawlistBuilderV1.reset
- Defined in core/src/drawlist/types.ts:98

setCursor

setCursor(state: CursorState): void
Set cursor position and appearance. Emits OP_SET_CURSOR (opcode 7).

Notes:
- x/y = -1 means "leave unchanged" (engine decides)
- visible = false hides the cursor regardless of position
- shape is ignored if the terminal doesn't support cursor shaping
Parameters
- state: CursorState
Returns void
- Defined in core/src/drawlist/types.ts:140

Interface DrawlistBuilderV2

Hierarchy (View Summary)

Index

Methods

Methods

addBlob

Parameters

Returns number | null

addTextRunBlob

Parameters

Returns number | null

build

Returns DrawlistBuildResult

clear

Returns void

clearTo

Parameters

Returns void

drawText

Parameters

Returns void

drawTextRun

Parameters

Returns void

fillRect

Parameters

Returns void

hideCursor

Returns void

popClip

Returns void

pushClip

Parameters

Returns void

reset

Returns void

setCursor

Parameters

Returns void

Settings

On This Page