@spec dimension(t(), Smith.Measure.t(), keyword()) :: {:ok, t()} | {:error, term()}

Adds a geometry-derived dimension to an immutable drawing.

Takes a Smith.Measure from the same source revision. Options: orientation: :aligned | :horizontal | :vertical (default aligned), offset: 5 mm, and precision: 2 decimal places (0–6). For linear dimensions, signed offset places the line above/below, right/left, or along the aligned segment's perpendicular. For angles, its absolute value is the annotation radius. Circular dimensions include center marks.

SVG includes extension lines, arrows, and measured labels in mm or degrees. Placement is explicit; automatic collision avoidance and driving constraints are not provided. Projected dimensions must retain the measured value; foreshortened or edge-on measurements return :dimension_out_of_plane. Stale measurements return :revision_mismatch. DXF currently rejects annotated drawings with :unsupported_annotations rather than losing labels.

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

Serializes a drawing to ASCII DXF (AutoCAD 2000 / AC1015).

Options are those in polylines/2. Coordinates retain local X/Y orientation with Z=0. $INSUNITS is 4 (millimeters). Each sampled edge becomes an LWPOLYLINE on the VISIBLE or HIDDEN layer. Closed edges use the closed flag and omit the duplicate endpoint. Curves are polylines, not DXF ARC, CIRCLE, or SPLINE entities.

VISIBLE uses continuous lines. HIDDEN uses a 2 mm dash / 1 mm gap linetype. Readers may apply their own display scaling to that pattern. Empty drawings produce a valid file without entities. This writer does not add dimensions, text, blocks, paper layouts, or toolpaths.

Returns {:ok, binary}; options and native errors follow polylines/2.

@spec new(source(), keyword()) :: {:ok, t()} | {:error, term()}

Evaluates a source and computes its orthographic drawing. Native OCEx.Shape values are also accepted as geometry snapshots.

Returns {:ok, drawing}. An existing result skips recipe evaluation; its BREP revision is checked before use. The drawing's source_revision identifies that source, while visible and hidden hold new native edge collections. Treat these fields as read-only.

Options:

• :on — :xy (default), :xz, :yz, or a Smith.Plane.
• :tangents — include smooth G1 boundaries between faces; default false.

The viewer looks along the plane's negative normal. Plane-local X points right and local Y points up. Coordinates are millimeters relative to its origin; moving the origin only along the normal has no effect. Surface seams and isoparametric lines are excluded. Coincident projected edges may remain; the drawing is not a joined cutting contour.

Assemblies show installed manufactured parts, excluding references and printable extras. To draw an exploded or display pose, pass the result of Smith.Assembly.view/2. Fetch a reference explicitly to draw it.

Unknown/duplicate options return :invalid_options, invalid frames return :invalid_plane, and stale input results return :revision_mismatch. Recipe and native geometry errors propagate.

@spec polylines(t(), keyword()) ::
  {:ok, %{visible: [[{float(), float()}]], hidden: [[{float(), float()}]]}}
  | {:error, term()}

Samples drawing curves into view-local XY polylines.

Returns {:ok, %{visible: polylines, hidden: polylines}}. Each polyline is a list of {x, y} points for one native edge, including both endpoints. Closed curves repeat the starting point. Separate edges are not stitched or deduplicated.

Options shared by SVG and DXF export:

• :tolerance — linear deflection in mm, default 0.03.
• :angular_tolerance — angular deflection in radians, default 0.1.
• :hidden — include hidden edges, default true.

Both deflections must exceed 1.0e-7. Sampling uses OCEx.polylines/3; tolerances control that algorithm and are not a certified global error bound for arbitrary splines. Empty layers return empty lists. Invalid options return :invalid_options; native failures propagate. Passing something other than a drawing returns :invalid_argument.

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

Serializes a drawing to a standalone SVG binary.

Supports the sampling options in polylines/2, plus:

• :padding — nonnegative margin in mm, default 5.
• :stroke_width — positive line width in mm, default 0.25.
• :title — XML text for the accessible title, default "Smith drawing".

SVG has explicit millimeter width/height and a viewBox matching drawing units. Its extent includes padding and half the stroke width at each boundary. Coordinates are reflected vertically for SVG's downward Y axis; the underlying drawing coordinates remain unchanged. Visible edges are solid black; hidden edges are gray with a 2 mm dash and 1 mm gap, painted first. Dimensions added with dimension/3 include measured labels and extension lines. There are no scripts or external assets.

Returns {:ok, binary}, or {:error, :empty_drawing} when the selected layers contain no points. Options and native errors follow polylines/2. Title text is escaped; invalid XML characters fail.

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

Writes an SVG or DXF file, inferring the format from its extension.

Returns {:ok, path}. Options belong to the selected serializer. The parent directory must exist; an existing file is overwritten only after serialization succeeds. File-system failures return their reason. Other extensions return :unsupported_format. This writes a single drawing file without a model bundle, print validation, or manifest. SVG supports measured annotations; annotated DXF export returns :unsupported_annotations.