[vjeux]

User need

A product that drags, flicks or throws an element has no public way to give it the motion Astryx's own components use: today it copies springs and decay curves by hand and loses Reduce Motion handling.

Problem and solution fit

The spec picks the small handle, so a product's drag stays in step with Core's components. Following the maintainers' API decision, useAnimator(ref) takes the element's ref, as the gesture hooks do, so a drag and an animation can share one element. The factory, the hook, both docs pages, both examples and their tests ship together: FR5 asks each hook to ship with its docs and a playing-cards example, and FR6 builds the hook on the factory.

Current specification

spec:AST-107 FR3 opens the touch components' animator as a public handle, with a non-React factory under the hook (FR6).

Public delta and caller burden

• createAnimator(element), from the package root only, returns animate, decay, set, get, getVelocity, stop and destroy over x, y, scale, rotate and opacity.
• useAnimator(ref), from @astryxdesign/core/hooks, takes the element's ref and returns the animator. After every commit it follows the element behind the ref: it attaches a node that mounts, moves to one that replaces it, and lets an unmounted one go; a remount, or a node that replaces it, starts at rest. It does this through useAttachment, the attach lifecycle the gesture hooks share, so it has no lifecycle of its own.
• decay coasts any channel; opacity stops at 0 or 1. Under Reduce Motion a thrown x or y keeps its momentum; anything else fades on a touch screen or lands at once with a mouse.
• The internal factory is renamed createMotionAnimator, so no internal factory shares a public factory's name. Its callers on main are renamed with it: the Slider's touch controller (feat(Slider): every pointer drags a thumb by its travel, as UISlider does #8190), the Switch's touch controller and its test's stand-in (feat(Switch): the touch presentation, for every pointer #9636), and the pager's tests (chore(core): a pager that pages like a UIKit paging scroll view #8146).
• In both playing-cards examples, the card is an image (role="img") named by its rank and suit, renamed on each deal, and one card leaves at a time: a Discard press while a card leaves, by a flick or by the button, deals no second card, and a press on the leaving card does nothing. A press on a card that is fading in moves only its position, so the fade runs on. A drag that the browser cancels springs back instead of being thrown.
• When the element behind useAnimator's ref unmounts, or a node replaces it, the animator's values return to rest, so a remount or a new node starts from the element's resting values.
• spec:AST-107 records the owner's decision on four edge behaviors of the public animator and pan gesture as DEC-4. FR1: a cancelled pan reports velocity {0, 0}. FR6: createPanGesture's destroy() during a drag reports cancelled once, usePanGesture's unmount reports nothing, and an opacity decay stops at 0 or 1, which createAnimator already does. FR3: a remount starts from the element's resting values. The pan sentences describe the public pan that comes next in this stack, which already behaves this way; they sit here so the record changes in one place.
• The core API report gains the animator's rows: function createAnimator, hook useAnimator, and the Animator, AnimatorAnimateOptions, AnimatorChannel, AnimatorDecayVelocity, AnimatorHandle, AnimatorSnapshot and AnimatorValues types. spec:AST-107 FR3 decides the handle and its channels, and FR6 the factory under the hook. Regenerating the report on this head also rewrites rows that main changed without updating it (text input props, some style hashes); those are left out, so this pull request adds only its own rows.

Left out.

• decay sets no bound on scale, as the record sets none, so a fast shrink can coast below 0. Stopping it at 0, as opacity stops at its edges, is a behavior change for the owners to rule on.
• animate following the theme's tempo and character (spec:AST-108 FR3) arrives with feat(core): the animator's springs follow the theme's tempo and character #8677, which makes the springs read the theme.
• The React playing-cards example rewritten on usePanGesture, a drag and an animation sharing the card's one ref, lands right after feat(core): createPanGesture and usePanGesture report a drag as values (spec:AST-107 FR1, FR6) #8655.

Effect on other open pull requests. The internal factory's rename to createMotionAnimator breaks six open drafts that import it as createAnimator from the motion module: #8065, #8145, #8189, #8496, #8677 and #8686. Each one renames that import when it rebases; the factory's signature is unchanged. A temporary internal alias is not possible, since no internal factory may share the public factory's name.

Size. import {createAnimator} from '@astryxdesign/core' adds 37.9 KB minified, 14.0 KB gzip, and import {useAnimator} from '@astryxdesign/core/hooks' adds 38.4 KB minified, 14.2 KB gzip, measured with the size report's build options. Neither import reaches any gesture module, which the touch-support bundle test checks.

Pull request size. This pull request's own commit is 2,542 lines with tests, and no part of it can stack apart. spec:AST-107 FR5 reads "Each hook ships with docs and a playing-cards example", so the two playing-cards templates, their test and their registrations (709 lines) ship with the hooks. The rest is the two exports with their docs, changeset and API report rows (716 lines), and the tests that cover them (1,117 lines), which cannot land apart from the code they test.

Design and alternatives

• Expose the internal animator: everything, but every spring, curve and option becomes a compatibility promise.
• A small handle on five channels with no spring choice: products match Core, at the cost of tuning.

Evidence

• Red-first:
  • Discard twice, and Discard during a flick's fade: with the one-at-a-time guard removed from both examples, all four cases fail (two cards are dealt); with it, they pass. The recorder models takeover as the animator does: a new opacity target ends a running fade.
  • A cancelled drag after fast moves: fails on the previous examples, which threw the card, and passes here.
  • An unmount: "an unmount lets the element go and drops the values; a remount starts at rest" fails on the previous factory, which kept them, and passes here.
  • A replacing node: "follows the element behind the ref when the node is replaced, and the new node starts at rest" fails on the previous factory, which handed the values to the new node, and passes here.
  • A press on a card fading in: "a press on the card being dealt moves only its position: its fade-in runs on". With the press stopping every channel, the card stayed part-faded and shrunk after a gentle release; now only the position stops. It fails on a version with only the leaving-card guard.
  • A press on a leaving card: "a press on a card that is leaving is ignored: its fade runs on, and one card is dealt after it". On the previous examples the press stopped the fade, so the next card was dealt under the finger and the first move pulled it off its place. The recorder's stop now ends running fades, as the animator's does.
  • The card's role: the cases find the card by role="img" and its name, which fails on the previous examples.
  • The dealt card's name: "names the dealt card by its rank and suit" finds the next card by its name after a discard. It fails on the previous plain-JavaScript example, whose card stayed "Top card".
  • useAnimator's module test checks that the hook imports only the factory, useAttachment and React, and calls useAttachment(ref, attach, null).
• Gates. On this head, on main 6690e33: pnpm install --frozen-lockfile, build, type check, test:ui (18,899), the node suites (16,051, with 2 expected failures), check:repo, ASTRYX_STRICT_LINT=1 pnpm lint (0 errors), check:changesets, changeset coverage and check:knowledge pass. On a fresh Storybook build, the accessibility contracts of the two components whose touch controllers are renamed pass: Switch's (12 of 12) and Slider's, with its geometry contract (30 of 30). The public and internal animators' browser specs pass ×3 in Chromium pinned to 2 cores at 1 worker (72 of 72); the Switch interaction specs pass there too (58 of 58); and under the CI WebKit job's command both sets pass (67 passed; 15 skip by their own engine conditions). Merged with current main 7f1bace, the type check, the CLI's template, golden and doc-input tests (1,054) and the animator, Switch and template tests (168) pass.

Writing rubric results

spec:AST-107, with the sentences added to FR1, FR3 and FR6 and the new DEC-4:

R1 narration: none; the added sentences and DEC-4 state what the system does, in the present tense. DEC-4's decider and date sit in its Decider line, as in DEC-1 to DEC-3.
R2 research: none in the record.
R3 evidence: no verification cell names a pull request, issue or commit.
R4 rejected alternatives: DEC-4 rejects four, in one Rejected: line inside the decision; the other three decisions keep theirs.
R5 change references: none.
R6 open questions: the section reads "None", and nothing the added text answers was open there.

Scope

• One capability is added.
• Unrelated fixes, cleanup, and policy changes were removed or split.
• Consumer docs, focused tests, and migration evidence ship with the feature.
• Public text and artifacts contain no internal Meta context.

Testing

1. In the useAnimator playing-cards example, fling the top card: it coasts away, and the next card is dealt once it has faded.
2. Drag the card a little and let go: it springs back on its release velocity.
3. With Reduce Motion on, a fling still follows your throw, and the next card fades in.

pnpm exec vitest run --project ui packages/core/src/animator packages/core/src/hooks/useAnimator.test.tsx
pnpm test:interaction packages/core/src/animator/__tests__/createAnimator.interaction.browser.spec.ts --project chromium

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Nov 3, 2026 4:33am UTC

[astracat-bot]

AI review status for this pull request.

Review status	Updated
🔄 In progress (for maintainers only)	Nov 3, 2026, 4:33 AM UTC

[astracat-bot]

Approval waits on an engineering owner's decision about the governing spec: spec:AST-107 FR3–FR6, which defines createAnimator, the @astryxdesign/core/animator entry and useAnimator, is only in open #8600. On main, architecture:react-component-runtime INV13 and spec:AST-017 FR21 still keep motion internal, and architecture:public-component-api INV21 has no carve-out yet for a hook that wraps a factory. Any engineering owner can settle it by landing #8600 or by commenting /approve-spec <full head SHA> on this pull request, and the author may do so as an engineering owner. Whatever that decision, these need fixing:

• Land #8076 first and rebase: this diff carries 17,491 authored lines, and that stack alone differs from main by 15,672.
• scripts/motion-node-load.test.mjs still imports the renamed createAnimator from motion/animator and fails.
• The two playing-card templates need a Changeset naming @astryxdesign/cli, a refreshed ShadCN route lock and the Sandbox's static route list; lint, docsite-data and build-sandbox fail without them.
• The templates should read zero release velocity after a still pause and deal the next card once the old one fades, and the docs should call animate's motion Astryx's state-change spring rather than the theme's, since roles stay internal under spec:AST-094 DEC-11.

[Automated review]

[astracat-bot]

This still re-exports createAnimator from ./motion/animator, which this PR renames to createMotionAnimator. esbuild leaves the binding undefined, and the child-process test fails with TypeError: m.createAnimator is not a function. Lines 103, 106 and 115 need the same rename.

[astracat-bot]

The release velocity comes from the last 80 ms of moves and ignores how long the pointer rested before pointerup. A drag that stops and holds still for 600 ms before release still throws the card away (Chromium), although the template says a gentle release springs it back. spec:AST-100 FR2 reads zero after a still pause. Passing the release's timeStamp and returning zero when the newest sample is older than about 80 ms would fix it, here and in the plain-JavaScript template's onUp.

[astracat-bot]

This waits for the whole coast, about 800 px at 1,600 px/s. After Discard, the table stays empty and the live region silent for 4.55 s before the next card is dealt. Dealing and announcing once animate({opacity: 0}) resolves, then calling stop(), keeps the keyboard path responsive.

[astracat-bot]

"On the theme's state-change motion": the animator plays springs.stateChange's table value, and no theme can retune it while spec:AST-094 DEC-11 keeps the roles internal (the motion README says the same). "Astryx's state-change spring" would be accurate; the same wording is at line 77, in useAnimator.doc.mjs lines 33 and 38, in the changeset and in the createAnimator JSDoc.

[astracat-bot]

This names only @astryxdesign/core, but the two new playing-card templates ship as @astryxdesign/cli output, and CI lint's changeset coverage fails on that. A separate [feat] changeset naming @astryxdesign/cli would clear it (spec:AST-017 FR7).

[astracat-bot]

Approval waits on an engineering owner's decision about the governing spec: spec:AST-107 FR3–FR6, which defines createAnimator, the @astryxdesign/core/animator entry and useAnimator, is only in open #8600, while on main, architecture:react-component-runtime INV13 and spec:AST-017 FR21 keep the animator internal and architecture:public-component-api INV21 has no exception yet for a hook over a factory. Any engineering owner can settle it by landing #8600 or by commenting /approve-spec <full head SHA> on this pull request, and the author may do so as an engineering owner. Whatever that decision, these need fixing:

• Land #8076 first and rebase: this diff carries 17,530 authored lines, 15,672 of them from that stack.
• scripts/motion-node-load.test.mjs still imports the renamed createAnimator from motion/animator (lines 31, 103, 106 and 115), so its child-process test fails.
• useAnimator.doc.mjs line 33 still says calls work before the ref attaches, which this head no longer does.
• The templates should read zero release velocity after a still pause and deal the next card once the old one fades, and the docs and JSDoc should drop usePanGesture and useAnimatedLayout, which the package does not have yet, and call the motion Astryx's state-change spring rather than the theme's.

[Automated review]

[astracat-bot]

./motion/animator now exports createMotionAnimator, not createAnimator, so this re-export finds nothing and m.createAnimator(null) at line 103 throws in the child process: the second test fails whether the bundler stops on the missing name or leaves it undefined. Lines 103, 106 and 115 need the same rename.

[astracat-bot]

"It works before the ref attaches: the element shows its values when it mounts" no longer holds: before the ref attaches every call does nothing, as line 27 and the hook's test an animator used before its ref attaches does nothing and resolves at once say.

[astracat-bot]

The 80 ms window is measured back from the newest move, not from the release. After a fast drag that stops and holds still, no more moves arrive, so the release still reads the earlier speed and throws the card, although the copy says a gentle release springs back. Passing the release event's timeStamp and returning zero when the newest sample is older than the window would fix it, here and in the plain-JavaScript template's onUp.

[astracat-bot]

This waits for the whole coast: from the Discard button, 1,600 px/s travels about 800 px and settles about 4.5 s later, so the table stays empty and the live region silent long after the card has faded. Dealing and announcing once animate({opacity: 0}) resolves, then calling stop(), keeps the keyboard path responsive.

[astracat-bot]

usePanGesture is not in the package yet, so this public JSDoc points callers to a hook they cannot import.

[astracat-bot]

Two claims here go beyond the package: no theme can retune springs.stateChange while motion roles stay internal (spec:AST-094 DEC-11), so "Astryx's state-change spring" would be accurate, and useAnimatedLayout does not exist in the package yet. The same wording is at line 38, in useAnimator.doc.mjs lines 33 and 38, in the changeset and in the createAnimator JSDoc.

[astracat-bot]

Approval waits on an engineering owner's decision about the governing spec: spec:AST-107 FR3–FR6, which defines createAnimator, the @astryxdesign/core/animator entry and useAnimator, is only in open #8600, while on main, architecture:react-component-runtime INV13 and spec:AST-017 FR21 keep the animator internal and architecture:public-component-api INV21 has no exception yet for a hook over a factory. Any engineering owner can settle it by landing #8600 or by commenting /approve-spec <full head SHA> on this pull request, and the author may do so as an engineering owner. Whatever that decision, these need fixing:

• Land #8076 first and rebase: this diff carries 17,538 authored lines, 15,669 of them from that stack.
• useAnimator.doc.mjs line 33 still says calls work before the ref attaches, which this head no longer does.
• Both templates should read zero release velocity after a still pause, and deal and announce the next card once the old one fades rather than after the whole 4.5 s coast.
• The docs and JSDoc should drop usePanGesture and useAnimatedLayout, which the package does not have yet, and call the motion Astryx's state-change spring rather than the theme's.

[Automated review]

[astracat-bot]

Approval waits on an engineering owner's decision about the governing spec: spec:AST-107 FR3–FR6, which defines createAnimator, the @astryxdesign/core/animator entry and useAnimator, is only in open #8600, while on main, architecture:react-component-runtime INV13 and spec:AST-017 FR21 keep the animator internal and architecture:public-component-api INV21 has no exception yet for a hook over a factory. Any engineering owner can settle it by landing #8600 or by commenting /approve-spec <full head SHA> on this pull request, and the author may do so as an engineering owner. Whatever that decision, these need fixing:

• Land #8076 first and rebase: this diff carries 17,663 authored lines, 15,794 of them from that stack.
• useAnimator.doc.mjs line 33 still says calls work before the ref attaches, which the hook does not do.
• Both templates should read zero release velocity after a still pause, and deal and announce the next card once the old one fades rather than after the whole 4.5 s coast.
• The docs and JSDoc should drop usePanGesture and useAnimatedLayout, which the package does not have yet, and call the motion Astryx's state-change spring rather than the theme's.

[Automated review]

[github-actions]

PR Analysis Report

Current run: The current CI run concluded skipped. Current analysis is unavailable.

---

_{Generated by PR Enrichment workflow | View current CI run}

[astracat-bot]

Requesting changes: the public createAnimator and useAnimator match spec:AST-107 FR3–FR6, which is now on main, but this branch also carries the open #8076 and #8677 stacks (19,819 authored lines in all), so please land those first and rebase onto main. These fixes are needed in this pull request's own files:

• useAnimator.doc.mjs line 33 says calls work before the ref attaches; they do nothing until it does.
• Both playing-card templates should read zero release velocity after a still pause (a 150 px drag held still for 600 ms is still thrown away).
• Both templates should deal and announce the next card once the discarded one fades, not after the whole 4.5 s coast.
• The docs and the velocity JSDoc should drop useAnimatedLayout and usePanGesture, which the package does not export yet.

[Automated review]

[astracat-bot]

"It works before the ref attaches: the element shows its values when it mounts" no longer holds: before the ref attaches every call does nothing and resolves at once, as line 27, createAnimator.ts (inactive()) and the hook's test say.

[astracat-bot]

The window is measured back from the newest move, not from the release, so a drag that stops and rests before pointerup is still thrown: a 150 px drag held still for 600 ms lands at about 828 px in Chromium. Passing the release event's timeStamp to onUp and returning zero when the newest sample is older than 80 ms would fix it.

[astracat-bot]

This waits for the whole coast, so the next card comes about 4.5 s after Discard although the card is transparent long before. Dealing once animator.animate({opacity: 0}) resolves, then calling stop(), keeps the keyboard path responsive.

[astracat-bot]

Requesting changes: createAnimator and useAnimator match spec:AST-107 FR3–FR6, and the spec:AST-094 FR43 sentence this branch carries has an engineering owner's approval for this head, but two things need to change before it can merge.

• Land #8676 (or drop it from this branch) and merge main, so the diff holds only the animator: 3,026 of its 5,549 authored lines are #8676's.
• In the plain-JavaScript playing-cards example, name the card by its rank and suit and update that name on each deal; today every card is announced as "Top card".

[Automated review]

[astracat-bot]

With role="img" the rank and suit text is presentational, so this name is all a screen reader announces, and it stays "Top card" after every deal (dealNext changes only textContent). Naming the card by rank and suit here and updating the label in dealNext, as the React example does with card.name, lets screen-reader users hear which card is on top. The template test that finds the card by 'Top card' would change with it.

[astracat-bot]

Non-blocking: this comment and the one on wheelSegment (line 758) restate their fields' names, so dropping them loses nothing.

[vjeux]

Fixed in c0b9848: the plain-JavaScript example names the card by its rank and suit and renames it on each deal, as the React example does. A new case in both examples, "names the dealt card by its rank and suit", fails on 3bc9310's plain-JavaScript example.

On the stack: #8676 has merged and this branch is now on main, so the diff holds only the animator. The description's "Pull request size" line covers this pull request's own commit: spec:AST-107 FR5 keeps the playing-cards example with the hooks. The two GestureHost comments are #8676's lines, so I've passed them to its author.

[cixzhang]

/approve-spec c0b9848

[astracat-bot]

Requesting changes: createAnimator and useAnimator match spec:AST-107 FR3–FR6 and their tests pass, but the plain-JavaScript example mounts its deck from a mount-only useEffect (AnimatorPlayingCardsVanilla.tsx:164-169). Please move that work to a stable callback ref on the wrapper, which React 19 calls on attach and whose returned cleanup runs on detach, and drop the two refs; the inline comment has the shape. The size is over 2,000 lines, but the factory, the hook, their docs and both examples ship together as one API under FR5 and FR6, so no split is needed.

[Automated review]

[astracat-bot]

This mount runs once because the wrapper's elements attach, and it depends on no prop or state. A stable callback ref on the wrapper can do the same work and return its cleanup (Core's React peer is 19), which is the pattern the repository asks for when work is caused by an element attaching:

function mountTable(wrapper: HTMLDivElement | null) {
  if (wrapper == null) {
    return undefined;
  }
  const table = wrapper.firstElementChild as HTMLElement;
  const button = wrapper.querySelector('button') as HTMLButtonElement;
  return mountDeck(table, button);
}
// <div ref={mountTable} style={…}> with the table div and the button as plain children

That removes both useRefs and the Effect.

[vjeux]

Fixed in 6d3d599: the plain-JavaScript example mounts its deck from a stable callback ref on the wrapper, in your shape. React 19 calls it on attach and runs its returned cleanup on detach, so the Effect and both refs are gone. A new case, "takes its deck down when it unmounts", checks that the card is removed and the animator destroyed after an unmount.

[cixzhang]

/approve-spec 6d3d599

[astracat-bot]

Requesting changes: createAnimator and useAnimator match spec:AST-107 FR3–FR6, and the plain-JavaScript example now mounts its deck from a callback ref, but this head breaks Core once it merges into main.

• main now carries #8190, whose packages/core/src/Slider/sliderTouchController.ts still imports createAnimator from ../motion/animator (line 32), so after this pull request's rename to createMotionAnimator the merged tree fails Core's type check (TS2305) and every Slider thumb drag throws createAnimator is not a function (line 1189); please merge main and rename that import and call.

The size is over 2,000 lines, but the factory, the hook, their docs and both examples ship together as one API under FR5 and FR6, so no split is needed.

[Automated review]

[astracat-bot]

On main this rename misses one caller: #8190's packages/core/src/Slider/sliderTouchController.ts still imports createAnimator from this module (line 32) and calls it at line 1189. Git merges the two without a conflict, but the result fails Core's type check with TS2305, and the Slider's touch controller throws createAnimator is not a function on the first thumb drag (9 Slider tests fail on the merged tree; all 148 pass on main). Merging main and renaming that import and call to createMotionAnimator fixes it.

[vjeux]

Fixed in 234dda6, rebased onto current main: #8190's sliderTouchController.ts now imports and calls createMotionAnimator. No other importer of the old internal name is left in the repository. Type check and the Slider, motion, animator and hook unit suites pass on the merged tree.

[cixzhang]

/approve-spec 234dda6

[astracat-bot]

Recommending approval: createAnimator and useAnimator match spec:AST-107 FR3–FR6, and the Slider's touch controller now calls the renamed internal factory, so Core type-checks and the Slider tests pass on this head.

The pull request is over 2,000 lines, but the factory, the hook, their docs and both playing-cards examples ship together as one API under FR5 and FR6, so no split is needed. Springs that follow a theme's tempo and character (spec:AST-108 FR3) remain internal-animator work, as the description says.

[Automated review]

[vjeux]

Updated in 6921f57, rebased onto current main. The four behaviors you asked an owner to settle are now decided and recorded in spec:AST-107 DEC-4, with FR1, FR3 and FR6 stating them. useAnimator now drops its values when its element unmounts or a node replaces it, so a remount or a new node starts from the element's resting values; two new cases fail on the previous head. Both playing-card examples also ignore a press on a leaving card, and a press on a card fading in moves only its position, each with a case that fails without it.

[cixzhang]

/approve-spec 6921f57

[astracat-bot]

Changes requested: the animator, its hook, the examples and the record update look right, but the internal rename breaks a caller that landed on main after this head was pushed.

• packages/core/src/Switch/useSwitchTouch.ts (from #9636, now on main) still imports createAnimator from ../motion/animator and calls it three times, so with this pull request merged Core's type check fails and every Switch with a touch presentation throws createAnimator is not a function when it attaches; please merge main and rename that import, its three calls and the createAnimator key in the useSwitchTouch.test.ts mock to createMotionAnimator.

Non-blocking: the comment on REST in createAnimator.ts restates the values; a line saying a new or remounted element starts from them would keep only the reason.

[Automated review]

[astracat-bot]

With main merged, packages/core/src/Switch/useSwitchTouch.ts:26 (from #9636) still imports createAnimator from this module and calls it at :288, :291 and :296. Core's type check then fails (TS2305) and a touch-presentation Switch throws createAnimator is not a function when it attaches. Please rename that import, the three calls and the createAnimator key of the vi.mock('../motion/animator') stand-in in useSwitchTouch.test.ts too.

[astracat-bot]

Non-blocking (comment style): this restates the constant's values. Keep only the reason, for example /** A new or remounted element starts from these values. */.

[vjeux]

Fixed in 271fdeb, merged onto current main: useSwitchTouch.ts imports and calls createMotionAnimator, and its test's vi.mock('../motion/animator') stand-in carries that key. Before the rename, Core's type check failed with TS2305 and three Switch tests threw createAnimator is not a function; both pass now. The pager's tests, which landed on main since, are renamed too, and no other importer of the old name is left. The REST comment now keeps only its reason.

[cixzhang]

/approve-spec 271fdeb