Gate Optional Effect At The Shared Primitive Agent Skill

Gate an optional effect at the shared primitive

An optional decorative surface treatment — a blur, a refraction, a glow, anything the user can

switch off — has three parts: a stored preference, a way for the UI to read it, and the draw code.

Only the third one is shared. Wire the gate to the third one.

// adapted — one local, published by the app theme, default ON
val LocalDecorEnabled = staticCompositionLocalOf { true }

// inside AppTheme(…, decorEnabled: Boolean = true, …)
CompositionLocalProvider(
    LocalDecorEnabled provides decorEnabled,
    /* the theme's other locals */
    content = content,
)

// adapted — the primitive every surface already goes through
@Composable
fun Modifier.decorSurface(shape: Shape = CircleShape, …): Modifier {
    if (!LocalDecorEnabled.current) {
        // shape and hit target unchanged; only the draw
        return this.clip(shape).background(colorScheme.surfaceContainerHighest.copy(alpha = 0.8f))
    }
    return this.drawTheExpensiveThing(shape = shape, …)
}

Traps

Gating per call site is a registration list nobody finishes. Counted here: 10 files call the

primitive — a compact player, two alternate navigation bars, seven ordinary screens — while exactly

2 files anywhere in the tree *branch on* the setting (five mention it; the storage, the accessor and

the settings row do nothing else). One of the two is the compact player, so all seven screens never

checked: they reached for the shared component with no reason to suspect a flag existed, so the

toggle appeared to work — the two surfaces that *did* check it flipped — while every detail screen

kept drawing the effect. Same silence as nav-tab-registration-drift and

guard-on-every-trigger-path: a rule that lives in a list has to be re-applied by every future

author, and it will not be.

The default is true, not false. A staticCompositionLocalOf { false } reads like the safe

choice and is the opposite: every @Preview, every composition rooted outside the app theme, and any

second window that forgot to re-provide gets the *stripped* look with no error and no diff. Default

to the appearance the design assumes, so being outside the theme degrades to "looks right" rather

than "looks broken". Same reasoning as the null-means-outside-the-theme default in

force-dark-immersive-subtree, arrived at from the other direction.

staticCompositionLocalOf, not compositionLocalOf. The static kind does not track reads: a

change recomposes the whole subtree under the provider. That is exactly right for a value that moves

once, when a human flips a switch, and would be exactly wrong for something changing per frame. The

tracking kind would instead register ~19 read scopes that exist only to observe a value that almost

never changes.

The off path must return the same geometry. Keep the clip(shape) and whatever gives the

element its size — return a *different paint*, never a different box. Drop the clip and corners

square up; drop a size and every neighbour shifts, so the user's toggle silently reflows the screen

and the setting reads as broken rather than as a preference. The fallback here deliberately reuses

the flat surface the screens drew before the effect existed, so "off" is a state the design has

already been through, not a new one.

A platform where the setting does not exist provides true once, at the theme. Resolve it in

the single call that builds the theme (stored == TRUE || platform is the one with no switch), not

at each call site — that is the per-call-site trap re-entering through the back door.

Some call sites legitimately branch *before* composing, and those are a different question. Two

surfaces here pick a whole different composable rather than a different material: a bar that is a

capsule in one style and a row in the other, and a compact player that swaps its container. Those

read the raw setting because the choice is which tree to build, not how to paint one. Keep them

countable — here, eleven comparisons in two files — and make sure both paths read the same stored

value, or the bar can be in one mode while its buttons are in the other. When the two branches are

the *same control* in two materials, see flat-twin-shares-geometry-not-material.

Put the guard before the remembers. The off path returns *above* rememberGraphicsLayer() and

the interaction holder, so a disabled surface allocates no layer, starts no animation and installs no

pointer input — most of what the setting exists to save. A gate expressed as an enabled parameter

on the expensive draw modifier would already have paid for all three by the time it was read.

An overload without the guard is a hole in the gate. The primitive here has two overloads: the

simple one carries the guard, the layer-plus-luminance one does not, because its two callers are both

the compact player — one inner-gated, one on the platform that provides true unconditionally.

Defensible, and also exactly what a forgotten overload looks like. So is the third door below

both overloads: the bar reaches the draw modifier directly. Write the reason beside each.

Keep both branches at the same call site. Returning a different modifier chain from the *same*

composable is what lets the runtime swap materials cleanly. Hoisting the branch into the caller

(if (enabled) GlassButton() else FlatButton()) creates two different call sites, so every toggle

discards whatever state that subtree held — animation progress, focus, scroll — and the switch reads

as a flicker rather than a change of finish.

The theme's own parameter has a default too, and it must agree with the local's. The theme takes

decorEnabled: Boolean = true and hands it to a local defaulting to true; make one of those two

false and the behaviour depends on which path the code took to get there — a theme call that omits

the argument disagrees with a subtree composed outside any theme, for no visible reason.

Do not thread the flag through as a parameter. A decorEnabled: Boolean argument on the

primitive puts the decision back at the call site with extra ceremony: every caller must now pass it,

and a caller that forgets gets the default. The local is what makes forgetting impossible.

Verifying it

# 1. The gate: locals defaulting to on, and every guard that reads one. One declaration per
#    optional treatment, one reader — the primitive. A reader in a screen file is the trap.
grep -rn --include='*.kt' -e 'staticCompositionLocalOf { true }' -e 'if (!Local' . | grep -v '/build/'

→ observed: three lines — two theme-level locals defaulting to true (this gate and the is-dark

flag), and exactly one if (!Local….current) { guard, in the primitive.

# 2. Call sites still comparing the raw stored setting. These are the pre-branch exceptions above;
#    read each and confirm it picks a different COMPOSABLE, not a different material.
grep -rn --include='*.kt' -E 'is[A-Za-z]+Enabled ==' . | grep -v '/build/'

→ observed: 11 comparisons in exactly 2 files — the shell choosing between two navigation bars, and

two player containers. A third file here would be a screen that should be using the gated primitive.

# 3. Everything the gate covers. Derive the primitive's declarations from step 1's file rather than
#    typing names, then list every file that calls one of them.
PRIM=$(grep -rl --include='*.kt' 'if (!Local' . | grep -v '/build/' | head -1)
SYMS=$(grep -oE 'fun [A-Za-z]*\.?[A-Za-z]+\(' "$PRIM" | grep -oE '[A-Za-z]+\(' | sort -u | tr -d '(' | paste -sd'|')
grep -rlE --include='*.kt' "($SYMS)\(" . | grep -v '/build/' | grep -v "^$PRIM$"

→ observed: 10 files. One is the compact player from step 2, two are the alternate navigation bars

(only ever composed on the enabled branch), and the remaining **7 are ordinary screens with no idea

the setting exists** — that 7-vs-1 split is the whole argument for the local.

• By eye, and this is the check counting cannot do: screenshot a gated screen with the setting off

and on, at the same scroll position, and overlay them — anything that *moved* is an off path that

changed geometry instead of paint. Then open a preview with no theme wrapper: it must look on.