@mkbabb/glass-ui 7.0.0 → 9.0.0

package/dist/composables/motion/engage/engageLadder.d.ts

@@ -0,0 +1,86 @@
+import type { EngageRole } from "./engageEnvelopes.js";
+import type { SpringPresetName } from "../spring/springPresets.js";
+/** The five rungs of MOTION-CANON §4, in ascending engagement order. */
+export type EngageRungName = "rest" | "hover" | "press" | "engaged" | "modal";
+/**
+ * The four channels a rung may move (§4 G3). `geometry` is the only one with mass and
+ * therefore the only one a spring may drive; the other three are envelope territory.
+ */
+export type EngageChannel = "geometry" | "luminance" | "blur" | "light";
+/** One rung: what it moves, what it moves ON, and the guards it carries. */
+export interface EngageRungRow {
+    /** The rung name — the lookup key. */
+    readonly rung: EngageRungName;
+    /**
+     * The rank of this rung's LEADING channel. Exactly one channel leads at rank 0
+     * (§4 G2); `null` means the rung sits outside the rank system entirely, which is
+     * true of `rest` alone.
+     */
+    readonly rank: 0 | null;
+    /**
+     * The rank at which the WORLD channel follows the rung's lead, or `null` where the
+     * rung recruits no world. §4 gives the engaged veil +6 and the modal scrim +2.
+     */
+    readonly worldLagRank: number | null;
+    /** The geometry row this rung rides, by name. `null` = the rung moves no rect. */
+    readonly spring: SpringPresetName | null;
+    /** The light row this rung rides, by role. `null` = the rung drives no envelope. */
+    readonly envelope: EngageRole | null;
+    /** Every channel this rung is permitted to move. Length ≤ `CHANNEL_BUDGET` (G3). */
+    readonly channels: readonly EngageChannel[];
+    /** Whether the rung exists only on a fine pointer — `@media (hover: hover)` (G7). */
+    readonly pointerFine: boolean;
+    /** Whether at most one element in the document may hold this rung (G6). */
+    readonly singleton: boolean;
+    /** The rung's ONE job, in the register's own words. */
+    readonly comment: string;
+}
+/**
+ * §4 G3 — "no rung changes more than 2 of {geometry, luminance, blur, light}". The
+ * budget is the reason the ladder reads as one language rather than as five effects
+ * firing at once: a rung that moves three channels has stopped being a rung and become
+ * a scene.
+ */
+export declare const CHANNEL_BUDGET = 2;
+/**
+ * §4 HOVER — "size ≤8%". Stated as the multiplicative ceiling a hover scale may reach,
+ * so a component row's own token is checkable against the ladder without the ladder
+ * knowing that component exists. The shipped `--scale-hover` (1.08) sits exactly on it.
+ */
+export declare const HOVER_GEOMETRY_BUDGET = 1.08;
+/**
+ * Which channel each asymmetry law governs — the ruling the two roots' opposite
+ * charters force (see the header). A checker reads THIS rather than assuming one
+ * direction is universal.
+ *
+ * THE CONTROL SURFACE RUNS TWO CLOCKS, AND THIS IS THE LAW THAT KEEPS THEM APART.
+ * A control's colour/border/shadow legs are clocked by an ATTACK channel and a RELEASE
+ * channel, and neither may be re-pointed at the other:
+ *   · ATTACK is bounded ABOVE by `ACKNOWLEDGE_WINDOW_MS` — `--duration-control` (the
+ *     0.12s control beat, `@utility transition-control`) and `--engage-*-attack` both
+ *     sit inside it. The standing strike against the 0.2s calm clock at
+ *     `utilities/btn.css` is a statement about THIS channel and no other.
+ *   · RELEASE is bounded BELOW by its own attack, by `light` here. A release inside the
+ *     acknowledge window is not a faster acknowledgement, it is a cut.
+ * A gate or a seat that reads one channel's bound as universal will "fix" the other into
+ * nonexistence; that is the collision this constant exists to forbid.
+ */
+export declare const LADDER_EXIT_LAW: {
+    /** Spatial legs depart faster than they arrive; the generator ships 0.6 ×. */
+    readonly geometry: "faster-than-entry";
+    /** Light legs outlive their attack; the envelope table ships release > attack. */
+    readonly light: "slower-than-entry";
+};
+/**
+ * The ladder. Ordered by ascending engagement, which is also the order a control
+ * climbs: no rung may be reached without its predecessor being reachable.
+ */
+export declare const ENGAGE_LADDER: readonly EngageRungRow[];
+/** Look one rung up by name. */
+export declare function engageRung(rung: EngageRungName): EngageRungRow;
+/**
+ * The rungs that ride a given envelope role — the reverse index the light-channel
+ * gate reads so a role's CSS clock can be checked against every rung that consumes it
+ * without the check enumerating rungs by hand.
+ */
+export declare function rungsForEnvelope(role: EngageRole): readonly EngageRungRow[];

package/dist/composables/motion/index.d.ts

@@ -1,14 +1,14 @@
-export * from "./core/constants";
-export * from "./spring/useSpring";
-export * from "./spring/useSpringMount";
-export * from "./spring/useLiquidPress";
-export * from "./morph/useDragMorph";
-export * from "./morph/useElementMorph";
-export * from "./reveal/useLiquidReveal";
-export * from "./morph/useDockCtaReceive";
-export * from "./reveal/useBloomUp";
-export * from "./number/useNumericTransition";
-export * from "./number/useAnimatedNumber";
-export * from "./number/useAnimatedNumberMap";
-export * from "./number/useCountup";
-export { SPRING_PRESETS, springPreset, type SpringPresetRow, type SpringPresetName, } from "./spring/springPresets";
+export * from "./core/constants.js";
+export * from "./spring/useSpring.js";
+export * from "./spring/useSpringMount.js";
+export * from "./spring/useLiquidPress.js";
+export * from "./morph/useDragMorph.js";
+export * from "./morph/useElementMorph.js";
+export { asElement } from "./core/asElement.js";
+export * from "./reveal/useLiquidReveal.js";
+export * from "./morph/useDockCtaReceive.js";
+export * from "./number/useAnimatedNumber.js";
+export * from "./number/useAnimatedNumberMap.js";
+export { SPRING_PRESETS, springPreset, type SpringPresetRow, type SpringPresetName, } from "./spring/springPresets.js";
+export { ENGAGE_ENVELOPES, ENGAGE_ATTACK_CLASS, ACKNOWLEDGE_WINDOW_MS, engageEnvelope, engageAttackT90Ms, type EngageEnvelopeRow, type EngageRole, } from "./engage/engageEnvelopes.js";
+export { ENGAGE_LADDER, CHANNEL_BUDGET, HOVER_GEOMETRY_BUDGET, LADDER_EXIT_LAW, engageRung, rungsForEnvelope, type EngageRungRow, type EngageRungName, type EngageChannel, } from "./engage/engageLadder.js";

package/dist/composables/motion/morph/eyeglass.d.ts

@@ -0,0 +1,141 @@
+/**
+ * §C1: "On a hop it **spans origin and destination** (1.5×, max 1.6×) then retracts
+ * onto the destination." The ceiling, not the nominal — a hop whose real span is
+ * shorter than this spans its real distance and no further. The span law is
+ * geometry-true first and capped second.
+ */
+export declare const EYEGLASS_SPAN_MAX = 1.6;
+/**
+ * §C1 (v1b): "**1.22× vertical swell largest at travel extremes** — a slug piling at
+ * the wall." The cross-axis channel. It is a SWELL, not the reciprocal of the span:
+ * the body thickens as it piles into its travel, which is the whole reason the moving
+ * pill ends up taller than the bar it rides in.
+ */
+export declare const EYEGLASS_SWELL_MAX = 1.22;
+/**
+ * §C1: "**Leading edge outruns trailing 2:1** (one 83ms frame: −54 vs −28px)." The
+ * asymmetry that makes mid-travel "an egg leaning into travel" rather than a symmetric
+ * balloon. Expressed as the ratio itself so the origin below can be derived from it.
+ */
+export declare const EYEGLASS_EDGE_RATIO = 2;
+/**
+ * The transform-origin that PRODUCES the 2:1 asymmetry, measured as a fraction of the
+ * box's longitudinal extent FROM THE LEADING EDGE. Derived, never transcribed:
+ *
+ *   scaling a box of extent w by k about a point at fraction f from the leading edge
+ *   moves the leading edge by (1 − f)·(k − 1)·w and the trailing edge by f·(k − 1)·w,
+ *   so leading : trailing = (1 − f) : f, and (1 − f)/f = R ⇒ f = 1/(1 + R).
+ *
+ * At R = 2 that is exactly 1/3. One scale write, on the compositor, produces the whole
+ * asymmetry — no second channel, no per-edge animation, no layout.
+ */
+export declare const EYEGLASS_ORIGIN_FRACTION: number;
+/**
+ * §C1: "**It breaks its own track**: moving pill ~8px taller than the bar —
+ * `overflow:hidden` kills the organ", and the codex's own gloss, "licensed to overflow
+ * ~10% of height". The fraction of its own cross extent the body hangs outside the
+ * track on EACH side, DERIVED from the swell rather than transcribed beside it: a
+ * symmetric swell of s hangs (s − 1)/2 out per side, so 1.22 gives 11% — the same ~10%
+ * the seat wrote down, arrived at from the other measurement.
+ *
+ * Two independent numbers in the footage agreeing to a point is the corroboration; two
+ * independent numbers in SOURCE is a drift waiting to happen, which is why only one of
+ * them is written here. The figure is a LICENCE, not a target — the swell produces the
+ * overflow and this is what the track must be prepared to let through. A track that
+ * clips is not a tidier track, it is a dead organ.
+ */
+export declare const EYEGLASS_OVERFLOW_LICENSE: number;
+/**
+ * §C3 (the commit cascade) states its ladder in RANKS — "geometry(0) → annotation(+6) →
+ * content(≈+15) → light decay to +30" — and its clock in milliseconds: "recolour
+ * +80–160ms · page content commits +250–450ms · glow decays +500ms after geometry
+ * stops". One unit reconciles them and it is the display frame:
+ *
+ *   +6  × 16.67ms = 100ms  → inside the measured 80–160ms recolour band
+ *   +15 × 16.67ms = 250ms  → the measured content band's own opening edge
+ *   +30 × 16.67ms = 500ms  → the measured glow decay, exactly
+ *
+ * The rank ladder is therefore not a second clock — it is the same clock counted in
+ * frames, which is why the cascade reads as one gesture rather than four timers.
+ */
+export declare const CASCADE_RANK_MS: number;
+/** The ranks §C3 measures, by the name it gives each stage of the one gesture. */
+export declare const CASCADE_RANKS: {
+    /** The object itself. Rank 0 — the pill arrives at t0 and everything else is late. */
+    readonly geometry: 0;
+    /** The selected label taking its ink. §C3's "recolour +80–160ms". */
+    readonly annotation: 6;
+    /** Whatever the strip governs. §C3's "page content commits +250–450ms". */
+    readonly content: 15;
+    /** §C3: "the object stops, the light does not" — the wake's tail, +500ms. */
+    readonly light: 30;
+};
+/** A cascade rank in milliseconds. The ONE conversion; no site does this arithmetic. */
+export declare function cascadeRankMs(rank: number): number;
+/** One longitudinal interval on the travel axis, in the container's own coordinates. */
+export interface EyeglassInterval {
+    /** The leading-edge-most coordinate (left, or top on a vertical strip). */
+    readonly start: number;
+    /** The trailing-edge-most coordinate (right, or bottom on a vertical strip). */
+    readonly end: number;
+}
+export interface EyeglassSpanParams {
+    /** Where the body is leaving. */
+    readonly from: EyeglassInterval;
+    /** Where the body is arriving. */
+    readonly to: EyeglassInterval;
+    /**
+     * The track's own inner interval on the same axis. The body may not span past it —
+     * §C1's "Driven into the end it **clamps**, compressing against the bar's inner
+     * edge". Omit only where no track exists to clamp against.
+     */
+    readonly track?: EyeglassInterval;
+    /** The surface's declared ceiling; defaults to the measured `EYEGLASS_SPAN_MAX`. */
+    readonly spanMax?: number;
+}
+export interface EyeglassSpan {
+    /**
+     * The longitudinal scalar to write, ≥ 1. `1` means the body does not span — a
+     * same-tab commit, or a hop the ceiling has fully absorbed.
+     */
+    readonly span: number;
+    /**
+     * True when the ceiling or the track boundary shortened the geometric span. §C1's
+     * clamp is a REPORTED state, not a silent floor: a paint that wants to read
+     * "compressing against the bar's inner edge" has to know it happened.
+     */
+    readonly clamped: boolean;
+    /**
+     * `1` when travel runs toward increasing coordinates, `-1` when it runs back, `0`
+     * for no travel. The sign the origin below flips on.
+     */
+    readonly direction: -1 | 0 | 1;
+}
+/**
+ * The SPAN law. The body's transient extent is the union of where it is leaving and
+ * where it is arriving — that is what "spans origin and destination" means literally —
+ * expressed as a multiple of the DESTINATION extent, because the destination is what it
+ * retracts onto and therefore what the scale is relative to.
+ *
+ * Two fences, in this order, both of them geometry rather than taste:
+ *   1. the surface's ceiling (`spanMax`), and
+ *   2. the track's inner edge — the body is licensed to overflow its track on the CROSS
+ *      axis (`EYEGLASS_OVERFLOW_LICENSE`) and on that axis only. Longitudinally it
+ *      clamps, which is the compression §C1 photographs at the ends of the bar.
+ */
+export declare function eyeglassSpan(params: EyeglassSpanParams): EyeglassSpan;
+/**
+ * The cross-axis SWELL, largest at travel extremes. `frac` is the travel distance
+ * normalised by the container extent — the same geometry-relative fraction the writer
+ * already computes — so a neighbouring hop barely thickens and a full-strip jump piles
+ * into the wall.
+ */
+export declare function eyeglassSwell(frac: number, swellMax?: number): number;
+/**
+ * The `transform-origin` percentage along the travel axis that yields the 2:1 lead.
+ * Travelling toward increasing coordinates the leading edge is the FAR one, so the
+ * origin sits `EYEGLASS_ORIGIN_FRACTION` in from that end — i.e. at (1 − f) of the box.
+ * Travelling back it mirrors. Zero travel keeps the centre, so a same-tab commit cannot
+ * lean.
+ */
+export declare function eyeglassOriginPercent(direction: -1 | 0 | 1): number;

package/dist/composables/motion/morph/useDockCtaReceive.d.ts

@@ -1,9 +1,9 @@
 import { type ComponentPublicInstance, type Ref } from "vue";
-import { type ElementMorphPreset } from "./useElementMorph";
-/** The receive spring register — `snappy` (the crisp absorb default) or `bouncy` (the
- *  emphatic land-with-overshoot). Matches `useLiquidReveal`'s register so the two seams
- *  read as ONE family. */
-export type DockCtaReceivePreset = ElementMorphPreset;
+import { type ElementMorphPreset } from "./useElementMorph.js";
+/** The receive spring register — `dock` (coordinated travel, the crisp absorb default)
+ *  or `panel` (the emphatic land-with-overshoot). A CTA flying into a dock control IS
+ *  coordinated travel, so it rides the same row the members do. */
+export type DockCtaReceivePreset = Extract<ElementMorphPreset, "dock" | "panel">;
 export type DockCtaReceivePath = "fine" | "coarse" | "reduced-motion" | "no-target";
 export type DockCtaReceivePhase = "idle" | "receiving" | "settled" | "handed-off" | "completed" | "reset";
 export interface DockCtaReceiveBand {
@@ -61,7 +61,7 @@ export interface UseDockCtaReceiveOptions {
      * fires immediately.
      */
     dockControl: Ref<HTMLElement | ComponentPublicInstance | null>;
-    /** The spring register (default `snappy`). */
+    /** The spring register (default `dock`). */
     preset?: DockCtaReceivePreset;
     /** The ending congest blur radius in px (the CTA dissolves into the glass). Default 4. */
     blur?: number;

package/dist/composables/motion/morph/useElementMorph.d.ts

@@ -1,8 +1,10 @@
 import { type ComponentPublicInstance, type Ref } from "vue";
-import { type SpringPresetName } from "../spring/springPresets";
+import { type SpringPresetName } from "../spring/springPresets.js";
 /** A measured endpoint, or the morphed surface's own settled box. */
 export type MorphEndpoint = Ref<HTMLElement | ComponentPublicInstance | null> | "self";
-export type ElementMorphPreset = Extract<SpringPresetName, "snappy" | "bouncy">;
+/** The registers the FLIP runner drives: coordinated travel (the default), the fired
+ *  deploy, and the room-sized bloom its `useLiquidReveal` leaf defaults to. */
+export type ElementMorphPreset = Extract<SpringPresetName, "dock" | "panel" | "bloom">;
 export interface MorphChannels {
     opacity?: boolean;
     blur?: number;
@@ -38,8 +40,6 @@ export interface UseElementMorphReturn {
     progress: Readonly<Ref<number>>;
     measurement: Readonly<Ref<ElementMorphMeasurement | null>>;
 }
-import { asElement } from "../core/asElement";
-export { asElement };
 export declare function lockSpatialTransition(el: HTMLElement): () => void;
 export declare function prefersReducedMotion(): boolean;
 /**

package/dist/composables/motion/morph/useLeadTrail.d.ts

@@ -1,18 +1,23 @@
 import { type Ref } from "vue";
+/**
+ * The bounded velocity lag — `clamp(v·τ, ±ceil)`. The worm's trail edge and the
+ * carousel's interior content-lag are the same law over different quantities.
+ */
+export declare function trailOffset(velocity: number, tau: number, ceil: number): number;
 export interface UseLeadTrailOptions {
-    /** The lead spring response (2π/response = the natural frequency). Default 0.68. */
-    response?: number;
-    /** The lead spring damping ratio ζ. Default 0.64. */
-    damping?: number;
-    /** The trailing follower time constant, seconds. Default 0.27 (≈270ms). */
-    trailTau?: number;
+    /**
+     * The lag ceiling in px, re-read per frame so it can be a live geometry band
+     * (`clamp(pitch, |Δ|·0.55, 3·pitch)`). A plain number is a fixed ceiling.
+     */
+    ceil?: number | (() => number);
+    /** The elongation time constant, seconds. Default 0.08. */
+    tau?: number;
     /** Honor `prefers-reduced-motion: reduce` → `drive` seats instantly. Default true. */
     respectReducedMotion?: boolean;
     /**
-     * The per-frame writer the consumer supplies (the DOM-write path, NO reactive
-     * thrash). Called each rAF tick with the live numeric edges — the consumer
-     * projects its silhouette (for example, a barbell) off `lo`/`hi`. Also called
-     * once on `seat` so a static mount paints correctly.
+     * The per-frame writer. Called each rAF tick with the live numeric edges — the
+     * consumer projects its silhouette off `lo`/`hi`. Also called once on `seat`
+     * so a static mount paints correctly.
      */
     onFrame?: (edges: LeadTrailEdges) => void;
 }
@@ -20,27 +25,28 @@ export interface UseLeadTrailOptions {
 export interface LeadTrailEdges {
     /** The lead edge (px) — springs toward the drive target. */
     lead: number;
-    /** The trail edge (px) — lags then catches the lead. */
+    /** The trail edge (px) — the lead, offset by the bounded velocity lag. */
     trail: number;
-    /** `min(lead, trail)` — the trailing silhouette edge (direction-agnostic). */
+    /** The lead's velocity (px/s) — the elongation's own cause. */
+    velocity: number;
+    /** `min(lead, trail)` — direction-agnostic. */
     lo: number;
-    /** `max(lead, trail)` — the leading silhouette edge (direction-agnostic). */
+    /** `max(lead, trail)`. */
     hi: number;
-    /** True once the edges have re-formed on the target (the emergent release). */
+    /** True once the edges have re-formed on the target. */
     settled: boolean;
 }
 export interface UseLeadTrail {
-    /** The live lead edge (updated per frame; the consumer usually reads `onFrame`). */
+    /** The live lead edge (updated per frame). */
     readonly lead: Readonly<Ref<number>>;
     /** The live trail edge (updated per frame). */
     readonly trail: Readonly<Ref<number>>;
-    /** True while the worm has re-formed on the target (the rAF is parked). */
+    /** True while the morph has re-formed on the target (the rAF is parked). */
     readonly settled: Readonly<Ref<boolean>>;
     /**
      * Retarget the lead edge (px). The velocity carries — a retarget mid-flight
-     * re-seats the target, the spring continues from its LIVE `(position, velocity)`
-     * so interruption is free. Under PRM this SEATS instantly (zero in-between frames).
-     * The `drive(fractionalIndex→px)` seam consumed by carousel drag scrubbing.
+     * continues from the LIVE `(position, velocity)`, so interruption is free.
+     * Under PRM this SEATS instantly (zero in-between frames).
      */
     drive(target: number): void;
     /** Snap BOTH edges to `value` instantly (mount / resize / PRM). Paints once. */
@@ -49,21 +55,17 @@ export interface UseLeadTrail {
     dispose(): void;
 }
 /**
- * The two-edge lead/trail integrator — a spring LEAD + a damped TRAIL follower in
- * ONE rAF. The gap between the edges is the morph's live elongation; the trail
- * catching the lead is the emergent release. keyframes-FREE + vueuse-FREE. See the
- * module header for the pager-worm rationale.
+ * The two-edge morph driver — a governed spring LEAD and a velocity-derived TRAIL
+ * in ONE rAF, with ZERO per-frame style reads. See the module header for the law.
  *
  * @example
  * ```ts
  * const worm = useLeadTrail({
- *   onFrame({ lo, hi }) {
- *     // project the barbell off the two edges (no getComputedStyle)
- *     paintBarbell(lo, hi)
- *   },
+ *   ceil: () => elongationCeil(),          // clamp(pitch, |Δ|·0.55, 3·pitch)
+ *   onFrame: ({ lo, hi }) => paintBarbell(lo, hi),
  * })
  * worm.seat(centerOf(active))   // mount
- * worm.drive(centerOf(next))    // hop — the lead springs, the trail lags then reels in
+ * worm.drive(centerOf(next))    // hop — the gap peaks with the velocity, then is 0
  * ```
  */
 export declare function useLeadTrail(options?: UseLeadTrailOptions): UseLeadTrail;

package/dist/composables/motion/morph/useSelectionGroup.d.ts

@@ -1,22 +1,30 @@
 import { type ComputedRef, type Ref } from "vue";
-import { type SelectionOption } from "./useSelectionIndicator";
-import { type TabActivation } from "../../../components/tabs/composables/useTabRovingFocus";
+import { type SelectionDeform, type SelectionOption } from "./useSelectionIndicator.js";
+import type { SelectionValue } from "../../../components/_shared/selection.js";
+import { type TabActivation } from "../../../components/tabs/composables/useTabRovingFocus.js";
 /**
  * useSelectionGroup is the library's single headless selection engine. The dock
- * control run, `<SegmentedTabs>`, and
- * `<ToggleGroup type="single">` are the SAME thing — a roving-focus selection
- * strip with a traveling indicator. This composable assembles that ONE engine
- * from the shared parts, reka-free and engine-free so it
- * ships on `/motion-core`:
+ * control run and `<SegmentedTabs>` are the SAME thing — a roving-focus selection
+ * strip with a traveling indicator — and both compose it (BK #19 W-SELECTION-ONE
+ * made SegmentedTabs the second; the arm at `tests/gates/overfit-structure.test.ts`
+ * forbids a third assembly). `<ToggleGroup>` is the THIRD consumer, adopted at
+ * **BK #84 W-TOGGLE-ROW**: reka retired from that component entirely and it now
+ * feeds this engine from an item registry, taking the role-per-mode ARIA, the
+ * roving machine and the recenter while DECLINING the indicator — `indicatorRef`
+ * omitted, which is the "plain toggle row" the param below already named as a
+ * first-class caller. The C-1 `SelectionOption["value"]` widening landed with it
+ * (`string` → `SelectionValue`), so the engine's consumer set is THREE, and this
+ * doc says three. The assembly, reka-free and engine-free so it ships on
+ * `/motion-core`:
  *
- *   • the SELECTION MODEL — `single` (a `string`) | `multiple` (a `string[]`),
- *     driven off a caller-owned `model` ref (no shadow registry — the ONE
- *     registry discipline);
+ *   • the SELECTION MODEL — `single` (one scalar) | `multiple` (an array of them),
+ *     at the OPTION TYPE's own value (`O["value"]`), driven off a caller-owned
+ *     `model` ref (no shadow registry — the ONE registry discipline);
  *   • the ROVING MACHINE — `useTabRovingFocus` composed VERBATIM (exactly-one-
  *     tabstop, axis-derived arrows, Home/End, wrap, disabled-skip);
  *   • the ONE TRAVELING-INDICATOR WRITER — `useSelectionIndicator` (the
  *     center-anchored ResizeObserver measure + the `--stretch` squish), so the
- *     dock/tabs/toggle-group indicator is Safari-identical by construction;
+ *     dock and tabs indicator is Safari-identical by construction;
  *   • the RECENTER CALL — `el.scrollIntoView({inline:'nearest', block:'nearest'})`
  *     on every select, so a selection past the fold pulls itself into view.
  *
@@ -32,10 +40,13 @@ export interface UseSelectionGroupParams<O extends SelectionOption> {
     options: ComputedRef<O[]>;
     /**
      * The caller-owned selection model — the ONE registry (no shadow state). A
-     * `single`-mode group reads/writes a `string`; a `multiple`-mode group a
-     * `string[]`.
+     * `single`-mode group reads/writes one option value; a `multiple`-mode group an
+     * array of them. Keyed to `O["value"]` rather than fixed at `string` (BK #84
+     * C-1), so a caller whose options carry `SelectionValue` keeps its own scalar
+     * end to end and a caller whose options carry `string` sees exactly what it saw
+     * before — the widening is by DERIVATION, so it breaks nothing.
      */
-    model: Ref<string | string[] | undefined>;
+    model: Ref<O["value"] | O["value"][] | undefined>;
     /** `single` (default) | `multiple`. */
     mode?: ComputedRef<SelectionMode> | SelectionMode;
     /**
@@ -51,24 +62,51 @@ export interface UseSelectionGroupParams<O extends SelectionOption> {
     /** The container scroller root (observed by the indicator's ResizeObserver). */
     containerRef: Ref<HTMLElement | null>;
     /**
-     * The traveling-indicator element (the `--stretch` squish target). Omit (or
-     * leave null) for a group with no glide indicator (e.g. a paper-hairline
-     * strip or a plain toggle row) — the squish/measure then no-ops.
+     * The traveling-indicator element (the deform write target). Omit (or leave
+     * null) for a group with no glide indicator at all (a paper-hairline strip, a
+     * plain toggle row) — the SQUISH then no-ops, which is HEAD's accurate half and
+     * is restored here. ~~The MEASURE does not no-op, and BK #84's rewording asserted
+     * that it did: `useSelectionIndicator` attaches its `ResizeObserver`
+     * unconditionally — that is the Safari-identical guarantee — and
+     * `updateSingleSlider` keeps writing a `singleSliderStyle` such a caller never
+     * reads. Economizing it is the indicator writer's own change to make.~~
+     * [2026-08-08 · BK #71 W-EYEGLASS, RT-84O: the change was made, in the file this
+     * text routed it to. `updateSingleSlider` now returns before its first rect read
+     * when `indicatorRef` is null, so such a caller runs ZERO layout. What #84 wrote
+     * was true of #84's HEAD and is false of this one — the `ResizeObserver` still
+     * attaches unconditionally (that guarantee is untouched), and a strip that
+     * appears late is measured on arrival because the indicator is a CHILD of the
+     * container, so the container watcher already covers it.]
      */
     indicatorRef?: Ref<HTMLElement | null>;
+    /**
+     * What the travelling body is made of — `"plate"` (default, the full body and
+     * the eyeglass host), `"mark"` (a hairline: length only), `"none"`. STATED, not
+     * inferred: a multi-toggle group has no single travelling body, and that is a
+     * different fact from a hairline having no area, even though the old null-ref
+     * sentinel spelled both the same way.
+     */
+    deform?: ComputedRef<SelectionDeform>;
     /** Per-option item refs, index-aligned to `options`. */
     buttonRefs: Ref<HTMLElement[]>;
+    /**
+     * A per-commit side effect the CALLER owns, fired on every committed selection
+     * (pointer AND keyboard) before the model write — e.g. SegmentedTabs' press
+     * squish on the pressed button. The engine stays the one selection path; a
+     * caller that needs a local flourish hangs it here rather than forking `select`.
+     */
+    onSelect?: (value: O["value"], idx: number) => void;
 }
-export interface UseSelectionGroupReturn {
+export interface UseSelectionGroupReturn<V extends SelectionValue = string> {
     /** The active option values (one for `single`, N for `multiple`). */
-    activeValues: ComputedRef<string[]>;
+    activeValues: ComputedRef<V[]>;
     /** True when `value` is currently selected. */
-    isSelected: (value: string) => boolean;
+    isSelected: (value: V) => boolean;
     /**
      * Commit a selection at `idx` — writes the model (toggle in `multiple`),
      * fires the travel-squish, and recenters the item via `scrollIntoView`.
      */
-    select: (value: string, idx: number) => void;
+    select: (value: V, idx: number) => void;
     /** The roving tabindex for option `idx` (`0` for the tabstop, `-1` else). */
     rovingTabindex: (idx: number) => number;
     /** The strip-root keydown handler (axis-derived arrows + Home/End). */
@@ -80,6 +118,6 @@ export interface UseSelectionGroupReturn {
     /** The resolved group `role` (`radiogroup` | `tablist` | `group`). */
     groupRole: ComputedRef<SelectionRole>;
     /** The per-item ARIA attributes for `value`, role-per-mode. */
-    itemAttrs: (value: string) => Record<string, string>;
+    itemAttrs: (value: V) => Record<string, string>;
 }
-export declare function useSelectionGroup<O extends SelectionOption>(params: UseSelectionGroupParams<O>): UseSelectionGroupReturn;
+export declare function useSelectionGroup<O extends SelectionOption>(params: UseSelectionGroupParams<O>): UseSelectionGroupReturn<O["value"]>;