@spec fixed(
  [Rendro.Page.t()],
  keyword()
) :: Rendro.Document.t()

Creates a fixed-position document from a list of pages.

@spec flow(
  [Rendro.Block.t()],
  keyword()
) :: Rendro.Document.t()

Creates a flow document from a list of content blocks.

@spec link(
  Rendro.Block.t(),
  keyword()
) :: Rendro.Block.t()

Wraps exactly one authored block with a curated external URI or internal page target.

@spec measure_rows([Rendro.Table.row()], number(), Rendro.Document.t(), keyword()) ::
  {number(), [number()]}

Returns {header_height, row_heights} (in points) for rows laid out as a Rendro.table/2 of total width, using document's font metrics.

This is a read-only projection of the engine's OWN table measurement: it builds an ephemeral table, measures it through the same private measurement logic the paginator uses, and returns the geometry. It does not paginate, render, cache, or mutate any engine state, so PAGE-04 single-pass behavior is unchanged.

It exists so recipes can chunk transaction rows by the engine's actual row heights — rather than a recipe-local estimate that would drift into :content_overflow — and therefore place page breaks and carried/brought-forward rows on the correct pages.

table_opts are forwarded to Rendro.table/2 (e.g. :header, :columns). Raises ArgumentError if the table cannot be measured (e.g. unsupported glyph).

@spec put_default_font(Rendro.Document.t(), Rendro.FontRegistry.logical_name()) ::
  Rendro.Document.t()

Sets the default logical font for a document.

@spec register_embedded_file(
  Rendro.Document.t(),
  atom(),
  {:path, Path.t()} | {:binary, binary()},
  keyword()
) :: Rendro.Document.t()

Registers a document-level embedded file on a document.

@spec register_embedded_font(
  Rendro.Document.t(),
  Rendro.FontRegistry.logical_name(),
  {:path, Path.t()} | {:binary, binary()}
) :: Rendro.Document.t()

Registers an explicit embedded font source on a document.

@spec register_embedded_font_family(
  Rendro.Document.t(),
  Rendro.FontRegistry.logical_name(),
  %{
    required(Rendro.FontRegistry.embedded_variant()) =>
      {:path, Path.t()} | {:binary, binary()}
  }
) :: Rendro.Document.t()

Registers a four-variant embedded font family on a document.

@spec register_font(
  Rendro.Document.t(),
  Rendro.FontRegistry.logical_name(),
  keyword()
) ::
  Rendro.Document.t()

Registers a logical font name on a document.

@spec render_protected(Rendro.Document.t(), render_options(), keyword()) ::
  {:ok, Rendro.Artifact.t()} | {:error, Rendro.Error.t()}

Renders the document to an artifact and then applies the configured protection adapter.

@spec render_signed(Rendro.Document.t(), render_options(), keyword()) ::
  {:ok, Rendro.Artifact.t()} | {:error, Rendro.Error.t()}

Renders the document to an artifact and then applies the configured signing adapter.

@spec render_to_artifact(Rendro.Document.t(), render_options()) ::
  {:ok, Rendro.Artifact.t()} | {:error, Rendro.Error.t()}

Renders the document and returns a Rendro.Artifact which contains the PDF binary, a deterministic hash, diagnostics, and metadata.

@spec render_with_diagnostics(Rendro.Document.t(), render_options()) ::
  {:ok, binary(), Rendro.Document.t()} | {:error, Rendro.Error.t()}

Renders the document and returns the binary along with the fully populated document struct. Useful for inspecting layout or reading populated diagnostics.

final_doc.diagnostics is a list of user-inspectable structured maps. Stable common keys such as :level and :type are present on every entry, while event-specific optional keys may include :message, :page_index, :reason, and :keep_rule. This is the developer-facing layout-debug surface; telemetry remains the operational span surface.