MultiFocus

MultiFocus[F][X, A] = (X, F[A]) is cats-eo's multi-focus carrier: a structural leftover X paired with an F-shaped bundle of foci. A single carrier, specialised through the type parameter F, backs every optic that focuses more than one value at once — traversals, grates, algebraic lenses, and aggregating (Kaleidoscope) reads.

What you get: the optic's surface is exactly the intersection of cats's typeclass hierarchy on F with what the generic carrier body supports. Pick an F and the methods light up automatically — .modify (Functor), .foldMap (Foldable), .modifyA (Traverse), .at(i) (Representable), .collectMap / .collectList aggregation, and same-carrier .andThen — with no new carrier, law surface, or AssociativeFunctor instance to write.

For the mechanical intro see Optics → MultiFocus; for runnable patterns the Cookbook ships three end-to-end recipes that exercise the prototypical Grate / Kaleidoscope / PowerSeries-downstream shapes.

Sub-shapes

The choice of F selects a sub-shape, each suited to a different multi-focus job:

All five share one runtime shape — a leftover paired with a focus container — so they live as a single carrier rather than five. See Historical landmarks for that consolidation and its measured payoff.

The general flexibility win

MultiFocus[F][X, A] = (X, F[A]) is just a pair. The carrier ships no typeclass machinery of its own; it inherits whatever F brings.

That distinguishes cats-eo's encoding from monolithic-carrier alternatives — Monocle's per-family classes (Lens, Prism, Traversal, IndexedTraversal, …) bake the typeclass requirements into the carrier definition itself. Adding a new optic family means introducing a new carrier with a new typeclass set. cats-eo's existential encoding lets the user add a new F and the existing MultiFocus surface lights up automatically: .modify if F has Functor, .foldMap if F has Foldable, .modifyA if F has Traverse, .at(i) if F has Representable, same-carrier .andThen if F has Traverse + MultiFocusFromList. No new carrier file, no new law surface, no new AssociativeFunctor instance — the generic body in MultiFocus.scala covers it.

The sub-shapes are the demonstration: each is just a different F plugged into the same shape. The PSVec case adds a hand-tuned same-carrier specialisation (mfAssocPSVec) for perf, but its capability set is the generic one, lit up by cats.Functor[PSVec] etc. shipped in the companion.

The capability set

Every method below is gated on a typeclass that F either has or doesn't have. Bring an F to the table and the optic's surface is exactly the intersection of cats's hierarchy on F with what the generic body supports.

import cats.data.ZipList
import cats.instances.list.given
import cats.instances.option.given
import cats.instances.function.given
import dev.constructive.eo.optics.Optic.*
import dev.constructive.eo.data.MultiFocus
import dev.constructive.eo.data.MultiFocus.given
import dev.constructive.eo.data.MultiFocus.{at, collectList, collectMap}

.modify — Functor[F]

val listMF = MultiFocus.apply[List, Int]

listMF.modify(_ + 1)(List(1, 2, 3))
// res0: List[Int] = List(2, 3, 4)

mfFunctor[F: Functor] provides ForgetfulFunctor[MultiFocus[F]], which Optic.modify consumes. Functor[List] arrives via cats.instances.list.given; the same body lights up for Vector, Option, ZipList, PSVec, Function1[X, *], and any user-defined F: Functor.

.foldMap — Foldable[F]

listMF.foldMap(identity[Int])(List(1, 2, 3, 4))
// res1: Int = 10

mfFold[F: Foldable] provides ForgetfulFold[MultiFocus[F]]. The carrier-wide Optic.foldMap extension picks it up — no MultiFocus-specific extension method ships, the read-only escape flows through the carrier-generic body.

.modifyA — Traverse[F]

def safeRecip(d: Double): Option[Double] =
  if d == 0.0 then None else Some(1.0 / d)

val doubleMF = MultiFocus.apply[List, Double]

doubleMF.modifyA[Option](safeRecip)(List(1.0, 2.0, 4.0))
// res2: Option[List[Double]] = Some(List(1.0, 0.5, 0.25))
doubleMF.modifyA[Option](safeRecip)(List(1.0, 0.0, 4.0))
// res3: Option[List[Double]] = None

mfTraverse[F: Traverse] provides ForgetfulTraverse[MultiFocus[F], Applicative]. Failures short-circuit on whatever Applicative[G] the user supplies.

.collectMap — Functor-broadcast aggregation

val zipMF = MultiFocus.apply[ZipList, Double]

// Column-wise mean: aggregator sees the whole ZipList, returns
// the mean, the broadcast fills back through Functor[ZipList].map.
zipMF.collectMap[Double](zl => zl.value.sum / zl.value.size.toDouble)(
  ZipList(List(1.0, 2.0, 3.0, 4.0))
)
// res4: ZipList[Double] = cats.data.ZipList@b588d106

.collectMap[B](agg: F[A] => B) requires only Functor[F]. The aggregator collapses the entire F[A] focus to a single B; the broadcast F.map(_ => b) puts the aggregate back into every position, preserving the F-shape exactly.

.collectList — List-only cartesian collapse

listMF.collectList(_.sum)(List(1, 2, 3, 4))
// res5: List[Int] = List(10)

MultiFocus[List]-only, produces List(agg(fa)) — a one-element output regardless of input length. Reproduces the v1 Reflector[List]'s cartesian-singleton choice at the call site without a typeclass.

.at(i) — Representable[F]

val grateF = MultiFocus.representable[[a] =>> Boolean => a, Int]

val payment: Boolean => Int = b => if b then 100 else 0
// payment: Function1[Boolean, Int] = repl.MdocSession$MdocApp$$Lambda$17590/0x00007f884e7d9b90@5980cf9f
grateF.at(true)(payment)
// res6: Int = 100
grateF.at(false)(payment)
// res7: Int = 0

.at(i: F.Representation) reads the focus at a representative index — typed against the cats Representable[F] instance. For Function1[X, *] this is the natural apply(i) lookup; for custom Naperian containers the user's Representable witness defines the index space. Surface gated on Representable[F], which most Fs with Functor + Foldable + Distributive already admit.

Why two collect variants

The v1 Reflector[F] typeclass collapsed differently per F:

No single derivation from Apply[F] covers all four behaviours uniformly — picking one would have silently changed the v1 List semantics. The chosen split (Functor-broadcast as the carrier-wide default, List-cartesian as the call-site extension) is honest about the choice without cluttering the discipline surface.

Composability profile

MultiFocus[F] has shipped inbound bridges from every classical read-write family (conditional on F's typeclass set) and two outbound bridges: → ModifyF (write) and a restricted → Forget[F] read-only escape (multifocus2forget, available only when T = Unit). The remaining outbound directions are structurally rejected rather than absent — see Composition limits below.

Inbound bridges

Each inbound bridge produces a MultiFocus[F]-carrier optic that inherits the full capability set above without per-bridge surface work. The PSVec-specialised bridges (tuple2multifocusPSVec, either2multifocusPSVec, affine2multifocusPSVec) sidestep the generic Applicative[F] / Alternative[F] constraint because PSVec admits neither — instead they directly call PSVec.singleton / PSVec.empty and mix in MultiFocusPSMaybeHit for the Prism / Optional fast-paths inside mfAssocPSVec's body.

Same-carrier .andThen

Three AssociativeFunctor[MultiFocus[F], _, _] instances ship, specialised by F:

• mfAssoc — the generic body for F: Traverse + MultiFocusFromList. Covers List, Vector, Option, cats.data.Chain. Singleton fast-path via MultiFocusSingleton (so morphed Lenses skip the per-element F.pure round-trip).
• mfAssocFunction1 — the absorbed-Grate sub-shape's body for F = Function1[X0, *]. Z = (Xo, Xi); the rebuild is a closure-on-closure, no per-element accumulator. Lights up for MultiFocus.representable, MultiFocus.tuple, and Traversal.{two,three,four}.
• mfAssocPSVec — the absorbed-PowerSeries body for F = PSVec. Parallel-array AssocSndZ leftover (saves the per-element Tuple2 the generic body would build). AlwaysHit fast-path via MultiFocusSingleton, MaybeHit fast-path via MultiFocusPSMaybeHit (Prism / Optional inners skip the per-element wrapper allocation).

Outbound — ModifyF and a read-only Forget[F] escape

import dev.constructive.eo.compose.Composer
import dev.constructive.eo.data.ModifyF

val modify = summon[Composer[MultiFocus[List], ModifyF]].to(listMF)

modify.modify(_ * 2)(List(1, 2, 3))
// res8: List[Int] = List(2, 4, 6)

multifocus2modify[F: Functor] — closes the U → N gap for both the prior v1 kaleidoscope2setter and the latent never-shipped alg2setter. Like every other Composer[X, ModifyF], this does NOT enable multiFocus.andThen(modify) directly: cross-carrier .andThen goes through AssociativeFunctor[F] on a single carrier, and ModifyF deliberately doesn't ship one (the deferred-modify semantic doesn't fit composeTo / composeFrom). The morph value lives at the morph site, not at the chain site. Same-carrier modify.andThen(modify) does work — see the Modify section for the AssociativeFunctor[ModifyF] instance shipped in ModifyF.scala.

The second outbound bridge, multifocus2forget[F], expresses a MultiFocus[F]-carrier optic as a read-only Forget[F] — discard the structural leftover, keep the focused F[A]. It is the structural inverse of the forget2multifocus inbound bridge above and ships only for T = Unit optics: once Forget drops the leftover it can't reconstruct a T ≠ Unit target, and that same T = Unit restriction is what keeps the bidirectional Forget[F] ⇄ MultiFocus[F] pair from making Morph resolution ambiguous (see Composition limits below). It's the explicit-Composer companion to the carrier-wide .foldMap / .headOption / .length read methods.

Composition limits

One further outbound direction is structurally rejected outright, and the → Forget direction is rejected only for a different effect (G ≠ F) — the same-F case ships as the multifocus2forget escape above. The rationale lives at the bottom of MultiFocus.scala and in docs/research/2026-04-23-composition-gap-analysis.md §3.2.6:

• Composer[MultiFocus[F], Direct] (MultiFocus widens to Iso/Getter). Type-level encodable, but forgetful2multifocus already ships in the OPPOSITE direction. Adding the reverse would create a bidirectional Composer pair, which the Morph resolution explicitly forbids — both Morph.leftToRight and Morph.rightToLeft would match for any Iso × MultiFocus pair, surfacing as ambiguous-implicit and breaking every iso.andThen(multifocus) call site. Workaround: multiFocus.to(s)._2 for the read side.
• Composer[MultiFocus[F], Forget[G]] for G ≠ F (MultiFocus widens to a different effect's Traversal/Fold). Generic in S, T, A, B. The morphed to has the MultiFocus's F[A] in hand but must yield G[A], and with no relationship between F and G there's no way to convert one to the other. The same-F case (Forget[F]) is exactly the multifocus2forget read-only escape documented above (restricted to T = Unit), so it ships rather than being rejected. Users wanting fold/traverse semantics on a MultiFocus's slots reach for that escape, construct the Forget[F]-carrier optic directly, or stay on MultiFocus and use .foldMap / .modifyA.

Lens / Prism / Optional → MultiFocus[Function1[X0, *]] is also structurally absent: Function1[X0, *] lacks Foldable / Alternative, so the constraint set on tuple2multifocus[F: Applicative: Foldable] (and the Prism / Optional variants) doesn't fire for the Naperian carrier. The Iso bridge forgetful2multifocusFunction1 carries no constraint — it's the only inbound for the absorbed-Grate sub-shape — so chains of the form iso.andThen(MultiFocus.tuple[...]) and iso.andThen(Traversal.two(...)) work, but lens.andThen(grate) does not.

Worked examples

Three end-to-end recipes in the Cookbook cover the prototypical post-fold shapes:

• Recipe A — Prototypical Grate-shape via MultiFocus.tuple — the "broadcast a uniform A => B over a homogeneous tuple" idiom. Exercises the absorbed-Grate sub-shape MultiFocus[Function1[Int, *]].
• Recipe B — Prototypical Kaleidoscope-shape via .collectMap / .collectList — the "applicative-aware aggregation" idiom. Exercises the absorbed-Kaleidoscope reasoning across MultiFocus[ZipList] (length-preserving broadcast) and MultiFocus[List] (cartesian collapse).
• Recipe C — PowerSeries downstream composition (Lens → each → Lens) — the post-consolidation crown jewel: the absorbed-PowerSeries sub-shape MultiFocus[PSVec] lets .andThen continue past Traversal.each into a downstream Lens. The deleted Traversal.forEach shape (Forget[T]-based, terminal) couldn't.

Historical landmarks

This page absorbed the previous "Grate" and "MultiFocus" sections of optics.md in the post-fold doc sweep. The empirical justification for each absorbed carrier lives in a research spike on the worktree branch that landed it:

• AlgLens + Kaleidoscope merge — the foundational fold; Reflector[F] deleted, two .collect flavours (.collectMap Functor-broadcast and .collectList cartesian) replace the v1 typeclass. See docs/research/2026-04-28-multifocus-unification.md.
• Grate fold — the lead-position field's empirical dead-code deletion; +20% perf on Grate.modify; absorbed factories ship as MultiFocus.representable / MultiFocus.representableAt / MultiFocus.tuple. The spike's research doc was lost in consolidation; the surviving evidence is the carrier-doc comment in MultiFocus.scala and the absorbed factory code.
• PowerSeries fold — Snd[A] match-type vestige eliminated; mfAssocPSVec preserves the parallel-array AssocSndZ representation and both MultiFocusSingleton / MultiFocusPSMaybeHit fast-paths verbatim. JMH within ±5% of baseline at every size up to 1024. See docs/research/2026-04-29-powerseries-fold-spike.md.
• FixedTraversal [N] fold — Traversal.{two,three,four} rerouted through MultiFocus[Function1[Int, *]]; the FT-shape gains the inbound Iso ↪, outbound ↪ ModifyF, and same-carrier .andThen from the unified MF carrier — three new compositions the user can write today that pre-fold were all U. See docs/research/2026-04-29-fixedtraversal-fold-spike.md.

The current, compiler-pinned composition matrix (11 families, 121 cells) lives in Optics → Composition matrix; the historical gap analysis that tracked the fold cell by cell is docs/research/2026-04-23-composition-gap-analysis.md. The pre-spike analysis of MultiFocus[List] vs PowerSeries on the traversal-shape common case (1.5–2.6× slower, hence both carriers shipped pre-fold) lives in docs/research/2026-04-22-alglens-vs-powerseries.md; post-fold the gap is closed by mfAssocPSVec's parallel-array specialisation.

Constructors at a glance

// Generic factory — F[A] source, identity rebuild
def apply[F[_], A]: Optic[F[A], F[A], A, A, MultiFocus[F]]

// Cross-carrier lifts — focus is already F[A], inner gets A
def fromLensF[F, S, T, A, B](
  lens: Optic[S, T, F[A], F[B], Tuple2]
): Optic[S, T, A, B, MultiFocus[F]]

def fromPrismF[F: MonoidK, S, T, A, B](
  prism: Optic[S, T, F[A], F[B], Either]
): Optic[S, T, A, B, MultiFocus[F]]

def fromOptionalF[F: MonoidK, S, T, A, B](
  opt: Optic[S, T, F[A], F[B], Affine]
): Optic[S, T, A, B, MultiFocus[F]]

// Absorbed-Grate factories — F = Function1[F.Representation, *]
def representable[F: Representable, A]
  : Optic[F[A], F[A], A, A, MultiFocus[Function1[F.Representation, *]]]

def representableAt[F, A](F: Representable[F])(repr0: F.Representation)
  : Optic[F[A], F[A], A, A, MultiFocus[Function1[F.Representation, *]]]

// Absorbed-Grate.tuple — F = Function1[Int, *]
def tuple[T <: Tuple, A](using ValueOf[Tuple.Size[T]], Tuple.Union[T] <:< A)
  : Optic[T, T, A, A, MultiFocus[Function1[Int, *]]]

Traversal.each[T, A] and Traversal.{two,three,four} are shipped in dev.constructive.eo.optics.Traversal and produce MultiFocus[PSVec] / MultiFocus[Function1[Int, *]] carriers respectively.

Further reading

• Cookbook → Theme E (Algebraic / classifier) — the three end-to-end recipes that ground each absorbed sub-shape.
• Concepts → Composition — the carrier graph and the bridge / lattice diagrams.
• MultiFocus.scala — the canonical source for the carrier definition, capability traits, and Composer instances; bottom-of-file comment carries the structural-rejection rationale for the directions MultiFocus → Direct and MultiFocus → Forget[G].

The sub-shapes MultiFocus[F] unifies have a deeper literature:

• Chris Penner's articles on grates, Kaleidoscopes, and algebraic lenses (chrispenner.ca) — the original treatments of the families absorbed here.
• Profunctor optics, a categorical update (Clarke, Elkins, Gibbons, Loregian, Milewski, Pillmore, Román) — the categorical account that places grates, traversals, and algebraic optics in one framework.
• Co-Presheaf Optics (Bartosz Milewski).