feat(pen): brush opacity + highlighter multiply

Honor each brush's opacity/blend so the brushes feel distinct
(closes TODO(brush-opacity)).

- Shared paint resolver: a stroke's color alpha is multiplied by its
  brush opacity; ballpoint/pencil opacity is tied to pressure
  (per-stroke average this increment) so a ballpoint reads lighter
  than a solid fountain pen.
- Highlighter paints with BlendMode.multiply and draws once, so
  cross-stroke overlap darkens like a real marker while self-overlap
  doesn't.
- Applied across BOTH render paths (PenCanvas static/live painters and
  the PDF _PageOverlayPainter).

Pencil paper-grain texture still deferred (TODO brush-texture); brush
kind is not yet serialized (TODO brush-persist — next). analyze clean,
tests green.

lib/editor/canvas/ink_painters.dart

@@ -65,6 +65,34 @@ Path buildStrokePath(
   return path;
 }
 
+/// Mean point pressure (`pressure ?? 0.5`) of a [PenStroke], for the per-stroke
+/// opacity resolution (spec §3/§4 tie ballpoint/pencil opacity to pressure).
+double _avgPressure(PenStroke stroke) {
+  if (stroke.points.isEmpty) return 0.5;
+  var sum = 0.0;
+  for (final p in stroke.points) {
+    sum += p.pressure ?? 0.5;
+  }
+  return sum / stroke.points.length;
+}
+
+/// THE single fill [Paint] for a committed/live stroke, with the brush's
+/// resolved opacity (multiplied into the color's alpha) and blend mode applied
+/// — closes TODO(brush-opacity). Shared by [StaticInkPainter]/[LiveInkPainter]
+/// and the PDF overlay painter so both render paths composite identically.
+Paint paintForStroke(PenStroke stroke) {
+  final resolved = resolveStrokePaint(
+    stroke.brush,
+    stroke.color,
+    pressureAvg: _avgPressure(stroke),
+  );
+  return Paint()
+    ..color = resolved.color
+    ..blendMode = resolved.blendMode
+    ..style = PaintingStyle.fill
+    ..isAntiAlias = true;
+}
+
 /// Paints all committed strokes for the page. Repaints only when the stroke
 /// list identity or page size changes (kept behind a RepaintBoundary).
 class StaticInkPainter extends CustomPainter {
@@ -86,13 +114,9 @@ class StaticInkPainter extends CustomPainter {
       final path =
           buildStrokePath(stroke, pageSize, isComplete: true, thinning: thinning);
       if (path.getBounds().isEmpty) continue;
-      canvas.drawPath(
-        path,
-        Paint()
-          ..color = Color(stroke.color)
-          ..style = PaintingStyle.fill
-          ..isAntiAlias = true,
-      );
+      // Single drawPath per stroke ⇒ a highlighter's own self-overlap never
+      // darkens; cross-stroke overlap darkens via BlendMode.multiply (marker).
+      canvas.drawPath(path, paintForStroke(stroke));
     }
   }
 
@@ -268,13 +292,7 @@ class LiveInkPainter extends CustomPainter {
     final path =
         buildStrokePath(s, pageSize, isComplete: false, thinning: thinning);
     if (path.getBounds().isEmpty) return;
-    canvas.drawPath(
-      path,
-      Paint()
-        ..color = Color(s.color)
-        ..style = PaintingStyle.fill
-        ..isAntiAlias = true,
-    );
+    canvas.drawPath(path, paintForStroke(s));
   }
 
   @override

lib/editor/canvas/pen_editor_screen.dart

@@ -50,7 +50,7 @@ import '../persistence/sidecar_repository.dart';
 import '../ui/pen_settings_page.dart';
 import '../ui/thumbnail_grid.dart';
 import 'editor_tool.dart';
-import 'ink_painters.dart' show buildStrokePath;
+import 'ink_painters.dart' show buildStrokePath, paintForStroke;
 import 'input_diagnostics.dart';
 import 'pen_palette_widgets.dart';
 import 'pen_stroke.dart';
@@ -1689,13 +1689,10 @@ class _PageOverlayPainter extends CustomPainter {
       final path =
           buildStrokePath(stroke, size, isComplete: true, thinning: thinning);
       if (path.getBounds().isEmpty) continue;
-      canvas.drawPath(
-        path,
-        Paint()
-          ..color = Color(stroke.color)
-          ..style = PaintingStyle.fill
-          ..isAntiAlias = true,
-      );
+      // Single drawPath per stroke ⇒ highlighter self-overlap never darkens;
+      // cross-stroke overlap darkens via BlendMode.multiply (closes
+      // TODO(brush-opacity); shared resolver with the PenCanvas painters).
+      canvas.drawPath(path, paintForStroke(stroke));
     }
 
     // 3. Live stroke — read from the notifier at paint time, only for this page.
@@ -1704,13 +1701,7 @@ class _PageOverlayPainter extends CustomPainter {
       final path = buildStrokePath(live.stroke, size,
           isComplete: false, thinning: thinning);
       if (!path.getBounds().isEmpty) {
-        canvas.drawPath(
-          path,
-          Paint()
-            ..color = Color(live.stroke.color)
-            ..style = PaintingStyle.fill
-            ..isAntiAlias = true,
-        );
+        canvas.drawPath(path, paintForStroke(live.stroke));
       }
     }
 

lib/editor/engine/brush.dart

@@ -18,19 +18,21 @@
 // (per-brush perfect_freehand option tables). The numbers below are lifted from
 // that spec verbatim.
 
+import 'dart:ui' show Color, BlendMode;
+
 /// The four selectable brushes. Extensible: add a kind here + a preset in
 /// [kBrushPresets]. The eraser is NOT a brush — it stays a separate tool.
 enum BrushKind {
   /// Strong pressure→width (rnote Pow2 / quadratic), soft taper, solid ink.
   fountainPen,
 
-  /// Near-constant thin width; pressure carries opacity in a later increment.
+  /// Near-constant thin width; pressure carries OPACITY (the ballpoint "tell").
   ballpoint,
 
   /// Broad, flat width, translucent, square (uncapped) ends.
   highlighter,
 
-  /// Moderate width + (later) opacity from pressure (rnote Sqrt / √p), scratchy.
+  /// Moderate width + opacity from pressure (rnote Sqrt / √p), scratchy.
   pencil,
 }
 
@@ -41,9 +43,10 @@ enum BrushKind {
 /// path reads the perfect_freehand geometry fields ([pfThinning], [pfStreamline],
 /// [pfSmoothing], [simulatePressure]) plus the cap/taper flags.
 ///
-/// [opacity] / [blendMultiply] are carried NOW for the later compositing
-/// increment but are NOT yet applied to rendered geometry — see
-/// TODO(brush-opacity) at the render sites.
+/// [opacity] / [blendMultiply] drive the painters' compositing via
+/// [resolveStrokePaint] (closes TODO(brush-opacity)): opacity is multiplied
+/// into the stroke color's alpha (pressure-tied for ballpoint/pencil — see
+/// [resolveStrokeOpacity]) and [blendMultiply] selects [BlendMode.multiply].
 class BrushProfile {
   const BrushProfile({
     required this.kind,
@@ -101,12 +104,14 @@ class BrushProfile {
   /// Whether the ends taper to a point (fountain pen) (spec §4).
   final bool taper;
 
-  /// Per-stroke opacity hint in [0,1]. CARRIED NOW, applied in a later
-  /// increment — see TODO(brush-opacity). `1.0` = solid.
+  /// Per-stroke opacity in [0,1]; `1.0` = solid. For fountain pen / highlighter
+  /// this flat value is used; ballpoint/pencil derive opacity from pressure
+  /// instead (spec §3/§4) — see [resolveStrokeOpacity]. Applied by the painters
+  /// via [resolveStrokePaint] (multiplied into the stroke color's alpha).
   final double opacity;
 
-  /// Whether the brush should composite with `BlendMode.multiply` (highlighter
-  /// build-up / marker feel). CARRIED NOW, applied later — TODO(brush-opacity).
+  /// Whether the brush composites with [BlendMode.multiply] (highlighter
+  /// build-up / marker feel). Applied by [resolveStrokePaint].
   final bool blendMultiply;
 }
 
@@ -136,9 +141,9 @@ const Map<BrushKind, BrushProfile> kBrushPresets = {
     blendMultiply: false,
   ),
   // Ballpoint — spec §4: size~2.2, thinning 0.15, smoothing 0.5,
-  // streamline 0.55, near-constant width, linear pressure (gamma 1.0). Pressure
-  // → opacity is deferred (TODO(brush-opacity)); opacity hint carried at 1.0
-  // until then so geometry-only ballpoint is solid (not invisible).
+  // streamline 0.55, near-constant width, linear pressure (gamma 1.0). The
+  // "tell" is pressure → OPACITY (0.55 + 0.45·pressureAvg, resolved per-stroke
+  // in resolveStrokeOpacity); the flat opacity field below is the solid cap.
   BrushKind.ballpoint: BrushProfile(
     kind: BrushKind.ballpoint,
     baseWidthFraction: 0.0022,
@@ -155,9 +160,10 @@ const Map<BrushKind, BrushProfile> kBrushPresets = {
   ),
   // Highlighter — spec §4: size~22, thinning 0.0 (constant width),
   // smoothing 0.4, streamline 0.5, square (uncapped) ends, translucent +
-  // multiply build-up. opacity 0.35 / blendMultiply true carried now; the
-  // existing highlighter ships a 0x80 (50%) color alpha at capture, so the
-  // 0.35 hint is NOT yet applied — see TODO(brush-opacity).
+  // multiply build-up. opacity 0.35 / blendMultiply true are APPLIED via
+  // resolveStrokePaint: the 0.35 is multiplied INTO the color's existing alpha
+  // (the capture path ships a 0x80 / 50% translucent color), and the stroke
+  // composites with BlendMode.multiply (cross-stroke overlap darkens = marker).
   BrushKind.highlighter: BrushProfile(
     kind: BrushKind.highlighter,
     baseWidthFraction: 0.02,
@@ -173,9 +179,9 @@ const Map<BrushKind, BrushProfile> kBrushPresets = {
     blendMultiply: true,
   ),
   // Pencil — spec §4: size~3, thinning 0.5, smoothing 0.5, streamline 0.4,
-  // pressure pre-warped to √p (Sqrt = pressureGamma 0.5). Pressure→opacity and
-  // paper grain are deferred (TODO(brush-opacity) / TODO(brush-texture));
-  // opacity hint 0.9 carried now, not yet applied.
+  // pressure pre-warped to √p (Sqrt = pressureGamma 0.5). Pressure → OPACITY
+  // (0.35 + 0.55·pressureAvg, resolveStrokeOpacity) makes it lighter/scratchy;
+  // the 0.9 field is the solid cap. TODO(brush-texture): paper grain deferred.
   BrushKind.pencil: BrushProfile(
     kind: BrushKind.pencil,
     baseWidthFraction: 0.003,
@@ -194,3 +200,80 @@ const Map<BrushKind, BrushProfile> kBrushPresets = {
 
 /// Resolve the [BrushProfile] for [kind] (always present; const map).
 BrushProfile brushProfileFor(BrushKind kind) => kBrushPresets[kind]!;
+
+// ---- Compositing (opacity + blend) — closes TODO(brush-opacity) -------------
+//
+// perfect_freehand produces a single closed fill polygon per stroke; the
+// painters then fill it with ONE Paint. These helpers resolve that Paint's
+// alpha + blend mode from the stroke's [BrushProfile] so the four brushes feel
+// distinct (the ballpoint/highlighter/pencil "soul"), while geometry stays in
+// the freehand path. Both render paths (PenCanvas + the PDF
+// `_PageOverlayPainter`) call [resolveStrokePaint] so they can never diverge.
+
+/// Resolve the EFFECTIVE per-stroke opacity in [0,1] for [profile], given the
+/// stroke's AVERAGE pressure [pressureAvg] (already gamma-pre-warped at
+/// capture, but for opacity we want the raw feel of "how hard you pressed", so
+/// callers pass the mean of each point's `pressure ?? 0.5`).
+///
+/// PER-STROKE (not per-segment): one alpha for the whole stroke this increment.
+/// The spec (§3/§4) ties ballpoint/pencil opacity to pressure; fountain pen and
+/// highlighter use the profile's flat [BrushProfile.opacity]. Per-point opacity
+/// (splitting into pressure-banded sub-strokes — spec §4) is deferred.
+double resolveStrokeOpacity(BrushProfile profile, {double pressureAvg = 0.5}) {
+  final p = pressureAvg.clamp(0.0, 1.0);
+  switch (profile.kind) {
+    // Spec §4: ballpoint "tell" is pressure → opacity (near-constant width).
+    case BrushKind.ballpoint:
+      return (0.55 + 0.45 * p).clamp(0.0, 1.0);
+    // Spec §4: pencil darkens with pressure (firm, quick-darkening √p feel).
+    case BrushKind.pencil:
+      return (0.35 + 0.55 * p).clamp(0.0, 1.0);
+    // Fountain pen (solid 1.0) + highlighter (flat 0.35) use the profile value.
+    case BrushKind.fountainPen:
+    case BrushKind.highlighter:
+      return profile.opacity.clamp(0.0, 1.0);
+  }
+}
+
+/// Multiply [opacity] (0..1) into [argb]'s existing alpha channel and return the
+/// new ARGB int. Keeps any alpha the capture path already baked in (e.g. the
+/// highlighter's 0x80 translucent capture) so this composes WITHOUT
+/// double-counting — the profile opacity scales whatever alpha the color has.
+int applyOpacityToArgb(int argb, double opacity) {
+  final baseAlpha = (argb >> 24) & 0xFF;
+  final scaled = (baseAlpha * opacity.clamp(0.0, 1.0)).round().clamp(0, 255);
+  return (scaled << 24) | (argb & 0x00FFFFFF);
+}
+
+/// The fully-resolved fill [Color] + [BlendMode] for one stroke, so every
+/// painter can configure its `Paint` identically. [argb] is the stroke's stored
+/// color; [pressureAvg] is the mean point pressure (`pressure ?? 0.5`).
+///
+/// - [color]: stroke color with `profile`-resolved opacity multiplied into its
+///   alpha (pressure-tied for ballpoint/pencil; flat for fountain/highlighter).
+/// - [blendMode]: [BlendMode.multiply] for the highlighter (marker build-up:
+///   cross-stroke overlap darkens), [BlendMode.srcOver] otherwise. The stroke
+///   is still drawn ONCE per render (single fill polygon) so its OWN self-
+///   overlap never darkens — that single-draw invariant lives in the painters.
+class ResolvedStrokePaint {
+  const ResolvedStrokePaint({required this.color, required this.blendMode});
+
+  final Color color;
+  final BlendMode blendMode;
+}
+
+/// Resolve the paint config for a stroke drawn with [kind]. See
+/// [ResolvedStrokePaint]. TODO(brush-texture): pencil paper-grain texture is
+/// still deferred — opacity is enough for this increment.
+ResolvedStrokePaint resolveStrokePaint(
+  BrushKind kind,
+  int argb, {
+  double pressureAvg = 0.5,
+}) {
+  final profile = brushProfileFor(kind);
+  final opacity = resolveStrokeOpacity(profile, pressureAvg: pressureAvg);
+  return ResolvedStrokePaint(
+    color: Color(applyOpacityToArgb(argb, opacity)),
+    blendMode: profile.blendMultiply ? BlendMode.multiply : BlendMode.srcOver,
+  );
+}

lib/editor/engine/stroke_geometry.dart

@@ -88,10 +88,9 @@ List<Offset> freehandOutlinePoints({
 
 /// Build perfect_freehand [pf.StrokeOptions] from a [BrushProfile] (spec §4).
 ///
-/// TODO(brush-opacity): [BrushProfile.opacity] / [BrushProfile.blendMultiply]
-/// are NOT consumed here — geometry only this increment. The caller still paints
-/// fill color (with its own alpha) and BlendMode.srcOver; per-stroke opacity /
-/// BlendMode.multiply for ballpoint/pencil/highlighter lands later.
+/// Geometry only: [BrushProfile.opacity] / [BrushProfile.blendMultiply] are
+/// consumed by the painters' [paintForEditorStroke] / `paintForStroke` (via
+/// [resolveStrokePaint]), NOT here — this stays a pure outline recipe.
 pf.StrokeOptions _optionsFromBrush(
   BrushProfile brush, {
   required double size,
@@ -171,3 +170,36 @@ Path buildStrokeOutline(
   path.close();
   return path;
 }
+
+/// Mean point pressure (`pressure ?? 0.5`) of an [EditorStroke], for the
+/// per-stroke opacity resolution (spec §3/§4 tie ballpoint/pencil opacity to
+/// pressure).
+double _avgPressure(EditorStroke stroke) {
+  if (stroke.points.isEmpty) return 0.5;
+  var sum = 0.0;
+  for (final p in stroke.points) {
+    sum += p.pressure ?? 0.5;
+  }
+  return sum / stroke.points.length;
+}
+
+/// THE single fill [Paint] for an [EditorStroke], with the brush's resolved
+/// opacity (multiplied into the color's alpha) and blend mode applied — closes
+/// TODO(brush-opacity). Shared by the committed [Picture] and live painters so
+/// the EditorStroke render path composites exactly like the PenStroke one.
+///
+/// The stroke is drawn as ONE fill polygon, so a highlighter's own self-overlap
+/// never darkens; cross-stroke overlap darkens via [BlendMode.multiply]
+/// (marker build-up). TODO(brush-texture): pencil paper grain still deferred.
+Paint paintForEditorStroke(EditorStroke stroke) {
+  final resolved = resolveStrokePaint(
+    stroke.brush,
+    stroke.color,
+    pressureAvg: _avgPressure(stroke),
+  );
+  return Paint()
+    ..color = resolved.color
+    ..blendMode = resolved.blendMode
+    ..style = PaintingStyle.fill
+    ..isAntiAlias = true;
+}

lib/editor/render/live_ink_painter.dart

@@ -39,13 +39,7 @@ class LiveInkPainter extends CustomPainter {
         isComplete: false, thinning: thinning);
     if (path.getBounds().isEmpty) return;
 
-    canvas.drawPath(
-      path,
-      Paint()
-        ..color = Color(stroke.color)
-        ..style = PaintingStyle.fill
-        ..isAntiAlias = true,
-    );
+    canvas.drawPath(path, paintForEditorStroke(stroke));
   }
 
   @override

lib/editor/render/static_ink_painter.dart

@@ -58,13 +58,10 @@ class StaticInkPainter extends CustomPainter {
         final path = buildStrokeOutline(stroke, pageSize,
             isComplete: true, thinning: thinning);
         if (path.getBounds().isEmpty) continue;
-        rec.drawPath(
-          path,
-          Paint()
-            ..color = Color(stroke.color)
-            ..style = PaintingStyle.fill
-            ..isAntiAlias = true,
-        );
+        // One drawPath per stroke ⇒ highlighter self-overlap never darkens;
+        // cross-stroke overlap darkens via BlendMode.multiply (closes
+        // TODO(brush-opacity); shared resolver with the live + PenCanvas paths).
+        rec.drawPath(path, paintForEditorStroke(stroke));
       }
       return recorder.endRecording();
     });