scale_linewidth(): per-segment mapped line width

[schochastics]

Closes #188.

A mapped linewidth on mark_line(), mark_step() and mark_segment() now
draws. It routes to vellum::segments_grob(lwd = <vector>), so each segment gets
one constant width — the mean of its two endpoint values, which is stated in the
docs rather than left implicit.

vplot(pressure) |>
  mark_line(x = temperature, y = pressure, linewidth = pressure) |>
  scale_linewidth(range = c(0.5, 6))

What's here

• scale_linewidth() (+ a scale_linewidth_continuous() alias), mirroring
  scale_size(): range (default c(0.5, 4), in lwd units), limits,
  breaks, name. Exported, in _pkgdown.yml's scales section.
• The line emitters. .emit_line, .emit_step and .emit_segment switch to
  a per-segment segments_grob when linewidth is mapped. A step's width holds
  across each tread and blends across the riser; a segment is already one element
  per row, so it just takes the lwd vector.
• A legend, reusing the edge-width guide's key glyph (a short rule drawn at
  the break's width).
• The scalar path is untouched. A constant linewidth still emits one
  lines_grob — asserted in the tests, not assumed.

Caveats, documented not hidden

The width changes in visible steps at each vertex and round joins do not fill a
sharp corner: inherent to per-segment width, and the reason the smooth-taper half
(#165 / r-vellum/vellum#47) still exists. No backend can stroke one path at
several widths in a single call, so a mapped linewidth emits one path element
per segment in SVG/PDF — noted in scale_linewidth(), NEWS and the vignette,
since it matters for file size on dense data. The scale API is the one that a
future smooth taper would keep, so that lands as an emitter change.

Edge width vs line width

linewidth on mark_edges() still trains scale_edge_width(); the two scales
are split by mark, so a graph can map edge width and a line's width to different
variables. Two visible consequences:

• Breaking, minor: guides(linewidth = ) and lims(linewidth = ) now
  address the line-width scale (edge_width for edges) — they previously
  canonicalised to edge_width, so on a vgraph() they reached the edges. They
  now silently do not, because a declared scale for an untrained aesthetic is
  simply unused. Migration is guides(edge_width = ) / lims(edge_width = ),
  now locked by a test.
• A mapped linewidth on mark_line() / mark_step() / mark_segment() no
  longer trains the edge-width scale, so those three stop drawing a stray
  edge-width legend that changed nothing on screen. Note this is only those
  three: mark_rule(), mark_linerange() and mark_area() also document a
  linewidth, and a mapped one there still trains edge_width and still draws a
  legend advertising widths that do not render. Pre-existing, not touched here --
  they emit segments_grob already, so extending them is the same one-line
  change .emit_segment got, and is left as a follow-up.

Both are in NEWS.

Also handled

Polar / coord_trans (each segment is munched exactly as .xy_path() would
munch the whole polyline, and every piece keeps that segment's width), flip,
sketch=, and effects = list(glow()) — .emit_copies() widens only
params$linewidth, which a mapped width ignores, so the widening is carried
separately and added to each mapped width. Provenance rows are refined to the
drawn segments.

Review fixes

• A missing (NA) width no longer erases two segments. The endpoint mean
  made one NA poison both segments meeting at that vertex, and a non-finite
  lwd reaches the backend as width 0 — so a single missing value silently cost
  ~31% of a five-point line's ink. Each segment now falls back to whichever
  endpoint is known, so a missing value thins the line instead; only a segment
  with no known width at either end is dropped, and its provenance row goes with
  it. This matches how the other continuous aesthetics degrade — a mapped size
  with one NA costs one point, not two.
• Four NA tests (thinning, no ink lost, the both-ends-missing drop keeping
  provenance aligned, all-missing draws nothing) and one locking the
  guides()/lims() redirection plus its migration.
• params$.lwd_add is documented as an internal effect-copy channel.

Verification

R CMD check: 0 errors / 0 warnings / 0 notes. Full suite green (3264 passing).
New tests/testthat/test-scale-linewidth.R covers the trained scale and its
legend, the endpoint-mean widths, the byte-identical constant path, style-group
splitting, step and segment, polar/flip/sketch, the glow halo, and the
edge-width/line-width split. Rendered and eyeballed in PNG, SVG and PDF.

Docs updated: scale_linewidth(), mark_point/mark_area/mark_segment Rd,
NEWS, README, the scales-and-guides vignette, _pkgdown.yml, and
inst/examples/06-size-shape-scales.R.

🤖 Generated with Claude Code