MultiFocusK

Optional → MultiFocus[F] — mirror of either2multifocus over the Affine miss / hit split.

Optional → MultiFocus[PSVec]. Mixes in MultiFocusPSMaybeHit so mfAssocPSVec skips the per-element Affine[o.X, Unit] wrapper the generic path would build.

Optional → MultiFocus[PSVec]. Mixes in MultiFocusPSMaybeHit so mfAssocPSVec skips the per-element Affine[o.X, Unit] wrapper the generic path would build.

Prism → MultiFocus[F] — hit becomes a pure singleton, miss becomes Alternative[F].empty.

Prism → MultiFocus[PSVec] — lifts a Prism-carrier optic so prism.andThen(traversal) type-checks. Mixes in MultiFocusPSMaybeHit so the PSVec-specialised mfAssocPSVec body skips the per-element Either[o.X, Unit] wrapper the generic to path would build.

Prism → MultiFocus[PSVec] — lifts a Prism-carrier optic so prism.andThen(traversal) type-checks. Mixes in MultiFocusPSMaybeHit so the PSVec-specialised mfAssocPSVec body skips the per-element Either[o.X, Unit] wrapper the generic to path would build.

Forget[F] ↪ MultiFocus[F] — a Fold slots into the pair carrier with X = Unit.

Iso → MultiFocus[F]. Requires Applicative[F] to broadcast the Iso's plain A focus into a singleton F[A]; the write-back picks the singleton out (throws on cardinality ≠ 1).

Iso ↪ MultiFocus[Function1[X0, *]] — the Iso side of the grate-shaped surface. Iso's forward to: S => A is broadcast to every index, so the bundle it produces is index-free (broadcast) and a composite reading through it never has to sample an index.

The product is a Function1BroadcastOptic — a class because the optic is the one thing the carrier's sum cannot describe before a read: a broadcast optic builds exactly one value per position, so mfAssocFunction1 writes it through the class's own hook (Function1BroadcastOptic.broadcastFrom) rather than through a bundle read it did not build. The class also owns the one read of a bundle it did not build: an index-free bundle is read outright, and a tabulating one at the real index the RepresentativeIndex witness supplies — a defined answer, never a forged sentinel, and never a value the index types the Grate factories fix (Int, Boolean, Unit, singletons) have to supply themselves.

The using clause is the cost side of that contract, exactly as on main: index types with a canonical value resolve import-free off RepresentativeIndex; anything else is refused rather than guessed — no index is ever forged, and nothing else needs a stand-in either.

Same-carrier composition for MultiFocus[F] — traversal.andThen(traversal), F-parametric. Z = (Xo, F[(Xi, Int)]): the outer leftover plus, per outer focus, the inner leftover and its focus count, so composeFrom can carve the flat modified vector back into per-element slices (cursor over an array snapshot). Inners that mix in MultiFocusSingleton (the Lens bridge) take an always-hit fast path that skips the per-element inner fold. Flat focus order is the outer's traversal order, inner order within each element.

PSVec-specialised same-carrier composition. Where the generic mfAssoc body builds two intermediate List accumulators + materialises via fromList, this body writes directly into IntArrBuilder / ObjArrBuilder and stores the existential as parallel arrays in AssocSndZ, sidestepping the per-element (Xi, Int) Tuple2 the generic path pays. Fast paths for MultiFocusSingleton (always-hit, Lens bridge) and MultiFocusPSMaybeHit (Prism / Optional bridges) inners; reassembly hands each inner an O(1) PSVec.slice view. See docs/research/2026-04-29-powerseries-fold-spike.md.

ForgetfulFold[MultiFocus[F]] via Foldable[F] — folds the focus vector, discarding the leftover. Unlocks .foldMap / .headOption / .length / .exists.

ForgetfulFunctor[MultiFocus[F]] via Functor[F] — maps every focus, leftover untouched. Unlocks .modify / .replace on Traversal-family optics.

ForgetfulTraverse[MultiFocus[F], Applicative] via Traverse[F] — effectful rewrite of every focus in F's traversal order. Unlocks .modifyA / .all.

MultiFocus[F] ↪ Forget[F] — read-only escape: discard the structural leftover, keep the focused F[A]. An explicit carrier morph alongside the carrier-wide Optic.foldMap / .headOption / .length / .exists extension methods.

Structurally this is the inverse of forget2multifocus — both Composer directions ship. That's normally banned by the cats-eo Morph resolution invariant (a bidirectional pair makes Morph[Forget[F], MultiFocus[F]] ambiguous because both leftToRight and rightToLeft fire). The Composer ships anyway because:

1. The from side requires T = Unit (Forget loses the leftover, so it can't reconstruct a T ≠ Unit). Only T-Unit MultiFocus optics qualify, which the type system enforces at use sites.
2. Any chain-resolution ambiguity surfaces at forget.andThen(multifocus) / multifocus.andThen(fold) call sites — the user resolves by routing through the explicit Composer[..].to(o) form rather than .andThen.

Practical Morph fallout: if a user actually hits the ambiguity, they get a clear implicit-not- found message naming both Composers; the workaround is one extra .morph-shaped call.

MultiFocus[F] → ModifyF. Uniform Modify widening for any Functor[F].

Lens → MultiFocus[F]. Mixes in MultiFocusSingleton so the mfAssoc fast-path fires.

Lens → MultiFocus[PSVec]. GetReplaceLens fast-path elides the (s, get(s)) Tuple2 the generic body would build. The to body builds anonymous Optic values inline so MultiFocusSingleton can refer to o.X without tripping Scala 3's "class parent cannot refer to constructor parameters" rule.

Lens → MultiFocus[PSVec]. GetReplaceLens fast-path elides the (s, get(s)) Tuple2 the generic body would build. The to body builds anonymous Optic values inline so MultiFocusSingleton can refer to o.X without tripping Scala 3's "class parent cannot refer to constructor parameters" rule.

Generic factory: X = F[A], focus = fa, rebuild = identity.

Construct an index-free (broadcast) bundle on the Function1[X0, *]-shaped carrier: a is the focus at every index, and it is known without consulting one. The mirror of MultiFocusK.foci (F[A]-shaped consumers) for consumers that need the value itself.

Use it when an optic's source has no X0-index of its own — an Iso reshaped into this carrier (forgetful2multifocusFunction1), or any optic that broadcasts one focus across the index set. Compositions read the difference: an index-free outer is read once (not per index), and the write of a composite whose read was index-free stays index-free all the way out.

Reinterpret a Lens whose focus is already an F[A] as a MultiFocus optic over the elements — the container the Lens reads IS the focus vector; X and the rebuild pass straight through.

Reinterpret an Optional whose focus is an F[A] as a MultiFocus optic over the elements — the mirror of fromPrismF over the Affine miss / hit split (miss recycled covariantly, both directions).

Reinterpret a Prism whose focus is an F[A] as a MultiFocus optic over the elements — the miss branch surfaces as MonoidK[F].empty (zero foci) and passes the leftover back through the prism's build path on write.

Polymorphic counterpart to apply — allows focus type change (F[A] => F[B]), the Traversal.pEach analogue at the generic factory. Sound for the same reason: the rebuild is identity on the written-back F[B], so no B ever has to fit an A-shaped hole. This is what un-pins the collect flavours' element type — pApply[F, A, Row].collectWith(...) emits a different row type than it read.

Generic Function1-shaped factory — any Representable[F] container yields a MultiFocus[Function1[F.Representation, *]]-carrier optic over F[A] with focus A. Encoding: X = Unit, rebuild = F.Representation => A. On to(fa) snapshot F.index(fa); on from((_, k)) materialise via F.tabulate(k). The .modify(f) round-trip is exactly F.map(fa)(f).

Position is a read-time argument, never a property of the optic: the index is supplied per call by the .at(i) extension (g.at(i)(fa) == F.index(fa)(i)), and Representable has no canonical Representation to hand a constructor anyway — Function1[Boolean, *] has no privileged Boolean, and Function1[Nothing, *] has no index at all. So this factory takes no representative index, and the built optic carries none: X = Unit, and the whole index-parametric read lives in the focus bundle. (Pre-0.19 a second name, representableAt(F)(repr0), took exactly such an index; it built this same optic — see the changelog for the removal.)

Polymorphic homogeneous-tuple Function1-shaped factory. to(t) = ((), i => t._i), from((_, k)) materialises via Tuple.fromArray(Array.tabulate(size)(i => k(i))).

Pointwise ZIP of two containers — a Grate's reason for existing, and the one operation representable made possible but never exposed.

A Grate is ((F[A] => A) => B) => F[B]: unlike a Traversal it can see EVERY focus at once while rebuilding, which is exactly what combining two structures needs. Traversal cannot express this — it visits one focus at a time with no access to a second structure — and neither can modify. Here the shape is concrete: read both containers as index functions and tabulate their pointwise combination.

Lawful for any Representable[F] (no shape to mismatch — every representation point exists in both), and zipWith(fa, fa)(f) == F.map(fa)(a => f(a, a)).