@spec fit(t(), {number(), number()}, keyword()) :: {:ok, t()} | {:error, term()}

Uniformly sizes text to a {width, height} ink envelope, retaining placement.

Options: margin: 0 mm on each side, min_size: 0 mm em size, grow: false. Scales size and tracking together to preserve proportions. Default only shrinks. Returns a new recipe after remeasuring its geometry; it never clips, stretches or silently removes letters. :text_too_small means the required size is below min_size; :text_does_not_fit means remeasured bounds fail. This fits dimensions only; use validate/2 to verify the actual placement.

@spec layout(t()) :: {:ok, layout()} | {:error, term()}

Evaluates text and returns %{result: result, report: report}.

Report dimensions, ink_bounds and glyph origin/bounds are in local plane coordinates (mm); world_bounds describes the positioned BREP. baseline is the local baseline origin. advance includes whitespace and tracking. area is unioned filled area (mm²), faces counts connected face regions. font records SHA-256, face index, family and style. revision matches result. Glyph clusters are UTF-8 byte offsets, not character indices. Spaces have nil bounds. Glyph bounds precede union; overall bounds measure the final shape. No native handles or font bytes are included in the report.

@spec new(String.t(), keyword()) :: t()

Describes text without constructing geometry. Required: font: %Smith.Font{} and size: mm. Options:

• on: Smith.Plane.xy() and at: {0, 0} set plane and local anchor.
• align: {:min, :baseline} anchors the ink's left edge and baseline. X supports :min, :center, :max, :origin; Y supports :min, :center, :max, :baseline. Ink alignment excludes surrounding spaces.
• tracking: 0 adds mm between shaped clusters; nonzero disables optional ligatures. Required script shaping is retained.
• direction: :auto (:ltr or :rtl) and language: "" control shaping.

Unknown/duplicate options fail at evaluation. Unsupported glyphs return :missing_glyph; empty/whitespace-only text fails instead of making a blank tag.

@spec validate(t(), keyword()) :: {:ok, layout()} | {:error, term()}

Measures and checks actual local ink placement and visible height.

Required within: {{xmin, ymin}, {xmax, ymax}} is a local rectangular region. Options: margin: 0, min_height: 0, tolerance: 1.0e-6, all in mm. Returns the layout with report.status (:passed or :failed) and explicit measured checks. A produced report is not necessarily a pass. Malformed inputs return errors. This is a bounds/readability check, not a certified minimum stroke thickness or printer-resolution check; inspect a geometry preview and verify the final fused/cut solid with Smith.Inspection.

@spec write(layout(), String.t(), keyword()) :: {:ok, map()} | {:error, term()}

Writes a layout's measured JSON report, PNG preview and outline SVG together.

Takes the output of layout/1 or validate/2, preserving that exact snapshot. A new revision-named directory beneath root prevents stale overwrites. Options: width: 960, height: 320 in pixels. Both images look directly at the text plane. SVG contains geometry paths, so viewing needs no installed font. JSON includes artifact paths and the source revision; native resources and font bytes are excluded. A failed write may leave partial images but does not publish report.json. Returns directory, report, png and svg paths.