(*---------------------------------------------------------------------------
   Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
   SPDX-License-Identifier: ISC
  ---------------------------------------------------------------------------*)

(** Kitty Graphics Protocol Unicode Placeholders

    Support for invisible Unicode placeholder characters that encode image
    position metadata for accessibility and compatibility.

    {2 Image ID Requirements}

    When using unicode placeholders, image IDs must have non-zero bytes in
    specific positions for correct rendering:
    - High byte (bits 24-31): encoded as the third combining diacritic
    - Middle bytes (bits 8-23): encoded in the foreground RGB color

    Use {!next_image_id} to generate IDs that satisfy these requirements. *)

val placeholder_char : Uchar.t
(** The Unicode placeholder character U+10EEEE. *)

val next_image_id : unit -> int
(** Generate a random image ID suitable for unicode placeholders.

    The returned ID has non-zero bytes in all required positions:
    - High byte (bits 24-31) is non-zero
    - Middle bytes (bits 8-23) are non-zero

    This ensures the foreground color encoding and diacritic encoding work
    correctly. Uses [Random] internally. *)

val write :
  Buffer.t ->
  image_id:int ->
  ?placement_id:int ->
  rows:int ->
  cols:int ->
  unit ->
  unit
(** Write placeholder characters to a buffer.

    @param image_id
      Should be generated with {!next_image_id} for correct rendering.
    @param placement_id
      Optional placement ID for multiple placements of same image.
    @param rows Number of rows in the placeholder grid.
    @param cols Number of columns in the placeholder grid. *)

val row_diacritic : int -> Uchar.t
(** Get the combining diacritic for a row number (0-based). *)

val column_diacritic : int -> Uchar.t
(** Get the combining diacritic for a column number (0-based). *)

val id_high_byte_diacritic : int -> Uchar.t
(** Get the diacritic for the high byte of a 32-bit image ID. *)