glimmer-motion 0.0.0 → 0.1.0-unstable.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to `glimmer-motion` are recorded here.
+
+This file follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+`glimmer-motion` and `@cardstack/choreo` release in lockstep: every version
+of one is a version of the other, and `@cardstack/choreo` peer-depends on the
+exact `glimmer-motion` version it was released with.
+
+Pre-1.0 caveat: the public API is intentionally unstable. Minor and patch
+versions may change behavior until `1.0.0`.
+
+## [Unreleased]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cardstack Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,9 +1,233 @@
 # glimmer-motion
 
-This version is a placeholder. It reserves the package name so that
-releases can be published from the
-[cardstack/boxel](https://github.com/cardstack/boxel) monorepo through npm
-Trusted Publishing. It contains no code.
+The [Motion](https://motion.dev) engine for Ember. `{{motion}}`, `<Presence>`, `<LayoutGroup>`,
+Reorder and drag, verified by ports of Motion's own test suites.
 
-Real versions are published under the `unstable` dist-tag first, and
-under `latest` once a stable release is cut.
+`<Choreo>`, a changeset and a timeline over a whole render pass, is a separate package built on this
+one: [`@cardstack/choreo`](../choreo).
+
+```gts
+import { motion, Presence, LayoutGroup, to, spring } from 'glimmer-motion';
+
+<template>
+  <LayoutGroup>
+    <Presence @items={{this.cards}} @key={{this.keyOf}} as |card h|>
+      <div
+        {{motion
+          presence=h
+          layoutId=card.id
+          initial=(to opacity=0)
+          animate=(to opacity=1)
+          exit=(to opacity=0)
+          transition=(spring stiffness=300 damping=30)
+          drag='x'
+          dragSnapToOrigin=true
+        }}
+      >
+        {{card.title}}
+      </div>
+    </Presence>
+  </LayoutGroup>
+</template>
+```
+
+## Install
+
+```
+pnpm add glimmer-motion motion-dom motion-utils
+```
+
+Peers: `motion-dom` / `motion-utils` (pinned together), `ember-modifier`, `@glimmer/component`,
+`@glimmer/tracking`, `ember-source >= 5.4`. A v2 addon — Embroider and Vite apps consume it directly, with
+TypeScript types and Glint signatures.
+
+New here? The [guide](https://github.com/cardstack/choreo/blob/main/docs/guide.md) teaches this
+from a Glimmer card rather than from a React translation table.
+
+## Features
+
+- **Animation** — `initial` / `animate` / `exit`, keyframes, springs/tweens/inertia, variants with
+  propagation and stagger orchestration, motion values through `style`, SVG attributes, animation lifecycle events
+- **Layout** — `layout` FLIP animation with scale correction, `layoutId` shared-element transitions and
+  crossfade, `<LayoutGroup>`, nested/relative projection, portals, `layoutChange()` / `instantLayoutTransition()`
+- **Presence** — `<Presence>` with `sync` / `wait` / `popLayout`, `@initial={{false}}`, `@custom`,
+  nested `@propagate`, tracked `h.isPresent`
+- **Drag** — Motion's pan/drag session: axis lock, direction lock, constraints (object / element / ref,
+  re-measured on resize), elastic, momentum, snap to origin, `createDragControls()`, `whileDrag`,
+  drag + layout, scroll-while-drag, `correctParentTransform()` / `transformViewBoxPoint()`
+- **Gestures** — `whileHover` / `whileTap` / `whileFocus` / `whileInView` and their handlers,
+  `<MotionConfig>` tree defaults, `scrollProgress()` / `InView` over Motion's `scroll()` / `inView()`
+- **Reorder** — `<ReorderGroup>` / `<ReorderItem>`, axis `x` / `y` / `xy` (detected), auto-scroll
+- **Glimmer** — `.gts`, Glint signatures, named exports, plain-function template helpers
+  (`to` / `spring` / `tween` / `styles` / `start`), and `prefers-reduced-motion` honoured by default
+- **Testing** — `glimmer-motion/test-support`: `animationsSettled()`, `bounds()`, `shape()`,
+  `setupMotion(hooks)`, and `registerMotionReset()` for a layer that keeps document-wide state of
+  its own. No `sleep()` in a motion test
+- **Re-hostable** — host hooks are ~40 lines plus the components; everything above that line is
+  framework-free
+
+## API
+
+| export                                                                                                         | what                                                                                                             |
+| -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `motion`                                                                                                       | the modifier: Motion's props as named arguments, plus `presence` and `transformPagePoint`                        |
+| `Presence`                                                                                                     | `@items @key @mode @initial @custom @onExitComplete @propagate @parent @anchorX @anchorY`, yields `item, handle` |
+| `LayoutGroup`                                                                                                  | `@id @inherit`; hosts the render detector that snapshots layout before the DOM changes                           |
+| `ReorderGroup`, `ReorderItem`                                                                                  | `@values @onReorder @axis` yielding `group`; `@group @value` + forwarded motion args                             |
+| `layoutChange(fn)`, `snapshotAll()`, `requestSettle()`, `afterSettle(fn)`, `instantLayoutTransition(fn)`       | layout pipeline                                                                                                  |
+| `createDragControls()`, `DragControls`                                                                         | `useDragControls`                                                                                                |
+| `correctParentTransform(elOrRef)`, `transformViewBoxPoint(svgOrRef)`                                           | `transformPagePoint` helpers                                                                                     |
+| `MotionNode`, `postRender`, `setPostRender`, `flushPendingMounts`                                              | for re-hosting on another Glimmer runtime                                                                        |
+| `setParticipantHost`, `closestParticipantHost`, `defineParticipantArg`, `ParticipantHost`, `MotionParticipant` | the participant-host extension point (below)                                                                     |
+| `registerBusyProbe`, `BusyProbe`                                                                               | count a host's own in-flight work as motion (below)                                                              |
+| `motionValue`, `MotionValue`, `transformValue`, `styleEffect`, `frame`, `animate`                              | the engine's imperative surface (below)                                                                          |
+
+Deep imports (`glimmer-motion/motion`, `glimmer-motion/presence`, `glimmer-motion/reorder/group`, …) are the
+same modules.
+
+### Participant hosts
+
+`glimmer-motion/participant` lets a component that coordinates many motion elements (a choreography, a
+shared-element transition) take part in their lifecycles without the elements knowing about it. `<Choreo>`
+is built on it. The interface is public API under semver: a change to it is a breaking change for every
+host package.
+
+A host is an object that implements `ParticipantHost`, installed on an element it renders:
+
+```gts
+import { modifier } from 'ember-modifier';
+import {
+  type MotionParticipant,
+  type ParticipantHost,
+  setParticipantHost,
+} from 'glimmer-motion/participant';
+
+class Stage implements ParticipantHost {
+  register(participant: MotionParticipant) {
+    // on mount; return what to run on its teardown
+    return () => {};
+  }
+  claim(participant: MotionParticipant) {
+    // on teardown: true keeps its VisualElement mounted until participant.release()
+    return false;
+  }
+}
+
+const hosted = modifier((el: Element, [host]: [ParticipantHost]) => {
+  setParticipantHost(el, host);
+  return () => setParticipantHost(el, undefined);
+});
+
+const stage = new Stage();
+
+<template>
+  <div data-motion-host {{hosted stage}}>
+    <div {{motion id='card'}}></div>
+  </div>
+</template>
+```
+
+- **Who joins.** A `{{motion}}` element with an `id` or a `role` joins the nearest `data-motion-host`
+  ancestor when it mounts. `id` is identity across renders, and `role` is a group the host can select by.
+  Elements with neither never join.
+- **Discovery.** The `data-motion-host` attribute belongs in the host's markup, not in its modifier.
+  Modifiers install children-first, so a marked element whose host has not installed yet resolves to no host,
+  never to an outer one.
+- **Lifecycle.** `register` runs on mount. On teardown the node calls the function `register` returned, then
+  asks `claim`. A host that claims a leaving element owns its unmount: it calls `participant.release()` when it
+  is done, and `participant.exitComplete()` to let an enclosing `<Presence>` finish the exit.
+- **What a host sees.** `MotionParticipant` exposes `element`, `visualElement`, `id`, `role`, `isPresent`,
+  `layoutKey`, `ownAnimation` and `presenceManaged`. `visualElement` is motion-dom's `VisualElement`, so a host
+  package and glimmer-motion must resolve the same motion-dom.
+- **Host args.** A host can add named args to `{{motion}}`. It declares each one by augmenting
+  `ParticipantArgs` and registers it with `defineParticipantArg(name, apply)`. The modifier keeps the arg away
+  from the engine and calls `apply(element, value)` on every pass, with `undefined` when the arg is absent.
+  `defineParticipantArg` returns a remover. Put the augmentation in a module that the host package's public
+  declarations import, or it won't reach that package's consumers. `<Choreo>` declares `pack` this way:
+
+  ```ts
+  declare module 'glimmer-motion/participant' {
+    interface ParticipantArgs {
+      pack?: 'box' | 'content';
+    }
+  }
+  defineParticipantArg('pack', (el, pack) => {
+    /* … */
+  });
+  ```
+
+- **Busy probes.** A host whose work outlasts the engine's own animations (a timeline between steps, a
+  barrier waiting on another region) registers a `BusyProbe` with `registerBusyProbe(probe)`. The probe
+  answers `false` at rest or a short reason while busy, and `animationsSettled()` / `whatIsBusy()` from
+  `glimmer-motion/test-support` consult it alongside the frame loop and the projection tree. It returns a
+  remover: a probe over one host instance's state is removed in that instance's destructor, and a probe over
+  module-global state may stay registered for the life of the page.
+
+### The engine's imperative surface
+
+A few of the engine's own functions are exported from `glimmer-motion` directly, for code that drives motion
+values by hand rather than through `{{motion}}`. They are the engine's functions, not wrappers, so they run on
+the same frame loop as every `{{motion}}` element.
+
+| export                       | from                | what                                                                       |
+| ---------------------------- | ------------------- | -------------------------------------------------------------------------- |
+| `motionValue`, `MotionValue` | `motion-dom`        | create a motion value, and its type; pass one to `{{motion}}` in `style`   |
+| `transformValue`             | `motion-dom`        | a motion value derived from others, recomputed when they change            |
+| `styleEffect`                | `motion-dom`        | bind motion values to an element's style outside `{{motion}}`              |
+| `frame`                      | `motion-dom`        | schedule `read` / `update` / `render` work on the engine's frame loop      |
+| `animate`                    | `framer-motion/dom` | animate a motion value, an element or a selector; `motion`'s own `animate` |
+
+```ts
+import { animate, motionValue } from 'glimmer-motion';
+
+const x = motionValue(0);
+animate(x, 120, { type: 'spring', visualDuration: 0.4 });
+```
+
+This is the only route by which realm cards reach the engine: `motion-dom` itself is not shimmed into
+realms. The list is deliberately small. The engine's internals (`animateVisualElement`, `visualElementStore`
+and the like) stay unexported, and adding a name to it is an API change to glimmer-motion, reviewed like
+one.
+
+### React → Glimmer
+
+| React                            | here                                                      |
+| -------------------------------- | --------------------------------------------------------- |
+| `<motion.div …>`                 | `<div {{motion …}}>` — any tag, including SVG             |
+| `ref`                            | the element, or a `{current}` object filled by a modifier |
+| `useMotionValue`, `useTransform` | `motionValue`, `transformValue`                           |
+| `<AnimatePresence>`              | `<Presence @items @key>` yielding a handle                |
+| `useIsPresent()`                 | `h.isPresent`                                             |
+| re-render → layout snapshot      | a render pass inside `<LayoutGroup>`, or `layoutChange()` |
+| `<MotionConfig>`                 | pass `transition` / `transformPagePoint` per element      |
+| `useDragControls()`              | `createDragControls()`                                    |
+| `Reorder.Group` / `.Item`        | `<ReorderGroup>` / `<ReorderItem>`                        |
+
+## How it works
+
+Motion's React library is an engine (`motion-dom`) plus glue. This package is only the glue, redone for
+Glimmer, reproducing the ordering React gives the engine: construct parents-first, mount children-first
+after the render pass, snapshot layout before the DOM changes and measure after, announce presence after
+the commit, freeze a leaving element's props. `src/node.ts` (the per-element lifecycle), `src/layout.ts`
+(the settle pipeline) and `src/scheduler.ts` (one `postRender` host hook) have no Ember imports;
+`src/motion.ts` and the components are the Ember host adapter.
+
+`scroll()`, `scrollInfo()` and `inView()` are Motion's own, re-exported from `framer-motion/dom`, the
+React-free entry point of Motion's React package. `framer-motion` is a regular dependency; its React peers
+are optional and that entry never imports them.
+
+The pan/drag session, the gesture and animation features and the Reorder utilities are Motion's own
+modules too, inlined at build time from framer-motion's build. `VENDORED.md` lists them and the two places
+glimmer-motion's drag deliberately differs.
+
+The full story — why the engine is untouched, how the binding was built by porting Motion's test suites and
+what that surfaced — is in the
+[repository README](https://github.com/cardstack/choreo#readme).
+
+## Not ported (yet)
+
+`m` / `LazyMotion`, Reorder's `as`, server rendering.
+
+## License
+
+MIT. The engine, algorithms and tests are [Motion](https://motion.dev) (MIT, Motion Division).

package/VENDORED.md

@@ -0,0 +1,111 @@
+# Code from Motion
+
+glimmer-motion runs Motion's own code wherever Motion's code is framework-free.
+
+- **The engine.** `motion-dom` and `motion-utils` are peer dependencies, shared with the rest of the page.
+- **Scroll and in-view.** `scroll()`, `scrollInfo()` and `inView()` come from `framer-motion/dom`, a
+  regular dependency.
+- **Gestures, features and Reorder utilities.** These come from framer-motion's build, which its exports
+  map doesn't expose. `src/framer-motion-internals.ts` imports them by their `framer-motion/dist/es/…`
+  paths, and `rollup.config.mjs` resolves those paths on disk and inlines the modules into
+  `dist/framer-motion-internals.js`. That file carries framer-motion's MIT notice. The build fails if any
+  output chunk imports React or a framer-motion path other than `framer-motion/dom`.
+
+| inlined from `framer-motion/dist/es/` (and the modules they import)                    | used by                                           |
+| -------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `gestures/drag/index`, `gestures/drag/VisualElementDragControls`, `gestures/pan/index` | `src/features.ts`, `src/gestures/drag-gesture.ts` |
+| `gestures/drag/use-drag-controls` (`DragControls` only; the React hook is tree-shaken) | `src/gestures/drag-controls.ts`                   |
+| `gestures/hover`, `gestures/press`, `gestures/focus`, `motion/features/viewport/index` | `src/features.ts`                                 |
+| `motion/features/animation/index`, `motion/features/animation/exit`                    | `src/features.ts`                                 |
+| `components/Reorder/utils/{check-reorder,detect-axis,auto-scroll}`                     | `src/reorder/group.gts`, `src/reorder/item.gts`   |
+
+framer-motion ships no declarations for these modules. `src/framer-motion-internals.ts` declares the part
+of their surface glimmer-motion uses. A changed signature upstream compiles silently against the old
+declaration, which is why a bump PR diffs these modules' source (see [Bumping Motion](#bumping-motion)).
+
+## One engine, pinned together
+
+The workspace catalog in `pnpm-workspace.yaml` pins `framer-motion`, `motion`, `motion-dom` and
+`motion-utils` to exact versions, and a bump moves all four.
+
+- **One `motion-dom`.** It holds the engine's shared state: the frame loop, the drag lock, every
+  `MotionValue`. A second copy on the page is a second engine that the first can't see. glimmer-motion
+  takes `motion-dom` and `motion-utils` as peers, the inlined framer-motion code imports them, and the
+  test app and gallery depend on them directly. The root `overrides` resolve `framer-motion`,
+  `motion-dom` and `motion-utils` through the catalog, so no caret range pulls in a second copy.
+- **The versions framer-motion was released against.** `motion-dom` and `motion-utils` sit at the lower
+  bounds of the ranges the pinned framer-motion declares. glimmer-motion's peer ranges start at the same
+  versions, because its dist carries that framer-motion code.
+- **`motion` at framer-motion's version.** The test app and the gallery use `motion`, which depends on
+  the `framer-motion` release of its own version.
+
+## Adapted, not inlined
+
+Upstream paths in this table and the next are relative to framer-motion's `src/`. `scripts/bump-motion.mjs`
+reads both tables to build a bump PR's report, and fails when an upstream path is in neither release.
+
+| here                                   | upstream                                                                                                     |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `src/gestures/transform-page-point.ts` | `utils/transform-rotated-parent.ts`, `utils/transform-viewbox-point.ts` (React ref → element or `{current}`) |
+
+## Ported by hand
+
+The rest of `src/` that follows Motion re-implements its React glue for Glimmer. Each file below ports the
+behavior of the upstream modules beside it.
+
+| here                    | upstream                                                                                                                                                                 |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `src/node.ts`           | `motion/index.tsx`, `motion/utils/use-visual-element.ts`, `motion/features/layout/MeasureLayout.tsx`, `components/AnimatePresence/use-presence.ts`                       |
+| `src/layout.ts`         | `motion/features/layout/MeasureLayout.tsx`                                                                                                                               |
+| `src/layout-group.gts`  | `components/LayoutGroup/index.tsx`                                                                                                                                       |
+| `src/motion-config.gts` | `components/MotionConfig/index.tsx`                                                                                                                                      |
+| `src/presence.gts`      | `components/AnimatePresence/index.tsx`, `components/AnimatePresence/PresenceChild.tsx`, `components/AnimatePresence/PopChild.tsx`, `components/AnimatePresence/utils.ts` |
+| `src/reorder/group.gts` | `components/Reorder/Group.tsx`                                                                                                                                           |
+| `src/reorder/item.gts`  | `components/Reorder/Item.tsx`                                                                                                                                            |
+| `src/scroll.ts`         | `value/use-scroll.ts`, `utils/use-in-view.ts`                                                                                                                            |
+
+glimmer-motion's own suite (`tests/`, run with `pnpm test`) carries the ports of Motion's Jest suites and
+Cypress fixtures that pin the fidelity.
+
+## Deviations
+
+Each deviation is a subclass of upstream's class in `src/gestures/drag-gesture.ts`, overriding only the
+methods that differ.
+
+| class                                                        | change                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GlimmerDragGesture` (over `DragGesture`)                    | `unmount()` always calls `controls.cancel()`. Upstream keeps the pan session alive when a component unmounts mid-drag, because React 19 can unmount and remount during reorder reconciliation. Glimmer's keyed `{{#each}}` moves nodes instead, so an unmount really is the end of the gesture. Upstream's branch skips `cancel()`, and with it the release of `setDragLock`'s module-global lock, so an element removed mid-drag silently kills `onDragStart` / `onDragEnd` for every later drag on the page. |
+| `TextLockingDragControls` (over `VisualElementDragControls`) | Holds a document-wide text-selection lock (`src/gestures/lock-select.ts`) while a pan session is open. CSS on the dragged node doesn't stop the browser selecting nearby text once the pointer leaves it.                                                                                                                                                                                                                                                                                                      |
+
+## Bumping Motion
+
+The Motion Bump workflow (`.github/workflows/motion-bump.yml`) checks npm daily. Once a newer framer-motion
+release is older than pnpm's `minimumReleaseAge`, it runs `scripts/bump-motion.mjs`, which moves the four
+pins and glimmer-motion's peer ranges. The workflow then opens a PR from `motion-bump/<version>` and
+requests review from the reviewer it names (`REVIEWER`). The script runs locally too:
+`node scripts/bump-motion.mjs` prints the release a bump would take, and
+`node scripts/bump-motion.mjs --to <version> --write --report -` moves the pins and prints the PR body.
+Run `pnpm install` after it.
+
+Reviewing a bump PR:
+
+1. **CI.** Red CI is the signal. The Glimmer Motion Tests job runs the ported fidelity suites, the Choreo
+   Tests and Choreo Test App Tests jobs run the choreo suites, Lint runs `ember-tsc` over the choreo
+   packages, and glimmer-motion's build fails if an inlined module imports React or a framer-motion path
+   other than `framer-motion/dom`. A PR opened with the workflow's `GITHUB_TOKEN` starts no
+   `pull_request` workflows, so the workflow dispatches `ci.yaml` and `ci-lint.yaml` on the branch
+   itself. A push to the branch runs the rest.
+2. **The PR body.** It lists every inlined, adapted or ported module whose TypeScript changed between the
+   two releases, with diffs, read from the `sourcesContent` of framer-motion's `dist/es/**/*.mjs.map`.
+   - For a changed entry module, compare its exports with the declarations in
+     `src/framer-motion-internals.ts`, and its overridden methods with the subclasses in
+     `src/gestures/drag-gesture.ts`. Neither fails to compile when upstream changes a signature.
+   - Port a change in an adapted source into `src/gestures/transform-page-point.ts` by hand.
+   - Read a changed ported module against the Glimmer file the report names, and port what applies to
+     Glimmer. Neither typecheck nor the ported suites, which are frozen at the upstream revision they came
+     from, catch this drift.
+3. **Fixes** are ordinary commits on the bump branch.
+4. **Title.** The PR opens as `fix:`, for a catch-up. Retitle it `feat:` when upstream adds a capability
+   glimmer-motion exposes. The prefix covers glimmer-motion and choreo, which release together.
+
+To decline a release, close its PR: the workflow skips a release that has a bump PR, open or closed.

package/addon-main.cjs

@@ -0,0 +1,4 @@
+'use strict';
+
+const { addonV1Shim } = require('@embroider/addon-shim');
+module.exports = addonV1Shim(__dirname);

package/declarations/activity.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Is anything still moving?
+ *
+ * Ember Animated's maturity is not its sprite code, it is `animationsSettled()`
+ * — a test can say "when everything has stopped" instead of `sleep(200)` and
+ * hoping. This is the machinery under that: every part of the binding that can
+ * still have work outstanding registers a probe, and a probe answers with a
+ * short reason string while it is busy and `false` when it is not.
+ *
+ * The reason is not decoration. A test that times out waiting for motion is
+ * useless if all it can say is "timed out"; `whatIsBusy()` names the element
+ * and the property that never stopped, which is usually the bug itself.
+ *
+ * Deliberately NOT an `@ember/test-waiters` waiter, which would make plain
+ * `await settled()` block until animations finish. That reads well in a doc and
+ * is wrong here: the interruption suite exists precisely to click again while
+ * something is still in flight, and a blocking waiter would turn every one of
+ * those into a wait-for-completion — the tests would pass by no longer testing
+ * anything. Waiting for motion is a thing a test asks for, not a thing it gets.
+ *
+ * Probes are module-global rather than owner-linked because the things they
+ * watch are: the engine's frameloop, the projection tree and the beacon
+ * registry are all one per document, and a probe that could not see across an
+ * owner boundary could not see the far-match barrier at all. A probe over one
+ * element's or component's state is removed in its destructor, so nothing
+ * outlives its element; a probe over module-global state stays registered.
+ */
+/** busy → a short reason; idle → false */
+export type BusyProbe = () => false | string;
+/**
+ * Make a layer's own in-flight work count toward "motion is busy", so
+ * `animationsSettled()` and `whatIsBusy()` wait on it too. The probe runs on
+ * every settle check and answers `false` at rest or a short reason while busy.
+ * Returns the remover: a probe over one instance's state is removed in that
+ * instance's destructor; a probe over module-global state (Choreo's far-match
+ * barrier) may stay registered for the life of the page.
+ */
+export declare function registerBusyProbe(probe: BusyProbe): () => void;
+/** every reason the binding is not at rest, for a timeout message */
+export declare function whatIsBusy(): string[];
+export declare function isMotionIdle(): boolean;
+//# sourceMappingURL=activity.d.ts.map

package/declarations/activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,0CAA0C;AAC1C,MAAM,MAAM,SAAS,GAAG,MAAM,KAAK,GAAG,MAAM,CAAC;AAI7C;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,IAAI,CAK9D;AAED,qEAAqE;AACrE,wBAAgB,UAAU,IAAI,MAAM,EAAE,CASrC;AAED,wBAAgB,YAAY,IAAI,OAAO,CAOtC"}

package/declarations/features.d.ts

@@ -0,0 +1,2 @@
+export declare function initFeatures(): void;
+//# sourceMappingURL=features.d.ts.map

package/declarations/features.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"features.d.ts","sourceRoot":"","sources":["../src/features.ts"],"names":[],"mappings":"AAmDA,wBAAgB,YAAY,SAqE3B"}

package/declarations/framer-motion-internals.d.ts

@@ -0,0 +1,65 @@
+import type { Feature, VisualElement } from 'motion-dom';
+import type { Box, Point } from 'motion-utils';
+import type { ItemData, ReorderAxis } from './reorder/types.ts';
+type FeatureClass = new (node: VisualElement) => Feature<unknown>;
+export declare const AnimationFeature: FeatureClass;
+export declare const ExitAnimationFeature: FeatureClass;
+export declare const InViewFeature: FeatureClass;
+export declare const PanGesture: FeatureClass;
+export declare const FocusGesture: FeatureClass;
+export declare const HoverGesture: FeatureClass;
+export declare const PressGesture: FeatureClass;
+export interface DragControlOptions {
+    /** The distance after which dragging starts and a direction is locked in. */
+    distanceThreshold?: number;
+    /** Whether to snap to the cursor immediately when dragging starts. */
+    snapToCursor?: boolean;
+}
+/** The per-element drag state machine behind the drag feature. */
+export interface VisualElementDragControls {
+    addListeners(): () => void;
+    cancel(): void;
+    endPanSession(): void;
+    isDragging: boolean;
+    /**
+     * Private upstream. Set by `start()` to the session it opens and cleared by
+     * `endPanSession()`. The session's `end()` removes its listeners, and runs
+     * on every pointerup.
+     */
+    panSession?: {
+        end(): void;
+    };
+    start(originEvent: PointerEvent, options?: DragControlOptions): void;
+    stop(event?: PointerEvent): void;
+}
+export declare const VisualElementDragControls: new (visualElement: VisualElement<HTMLElement>) => VisualElementDragControls;
+export interface DragGesture extends Feature<HTMLElement> {
+    controls: VisualElementDragControls;
+    mount(): void;
+    removeGroupControls(): void;
+    removeListeners(): void;
+    unmount(): void;
+    update(): void;
+}
+export declare const DragGesture: new (node: VisualElement<HTMLElement>) => DragGesture;
+/**
+ * Start, stop or cancel a drag on every `motion` element given these controls
+ * as `dragControls`, from a pointer event anywhere on the page.
+ */
+export interface DragControls {
+    /** End the drag where it is: no momentum and no `onDragEnd`. */
+    cancel(): void;
+    /** Start a drag on every subscribed element, from `event`. */
+    start(event: PointerEvent, options?: DragControlOptions): void;
+    /** End the drag as a pointerup would: momentum, then `onDragEnd`. */
+    stop(): void;
+    /** Called by the drag feature of each element given these controls. */
+    subscribe(controls: VisualElementDragControls): () => void;
+}
+export declare const DragControls: new () => DragControls;
+export declare const checkReorder: <T>(order: ItemData<T>[], value: T, offset: Point, velocity: Point, axis: ReorderAxis, direction?: 'ltr' | 'rtl') => ItemData<T>[];
+export declare const detectAxis: (layouts: Box[]) => ReorderAxis;
+export declare const autoScrollIfNeeded: (groupElement: Element | null, pointerPosition: number, axis: 'x' | 'y', velocity: number) => void;
+export declare const resetAutoScrollState: () => void;
+export {};
+//# sourceMappingURL=framer-motion-internals.d.ts.map

package/declarations/framer-motion-internals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framer-motion-internals.d.ts","sourceRoot":"","sources":["../src/framer-motion-internals.ts"],"names":[],"mappings":"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"}

package/declarations/gestures/drag-controls.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Motion's DragControls (upstream's class, see framer-motion-internals.ts) and
+ * the Glimmer stand-in for its `useDragControls()` hook.
+ */
+import { DragControls } from '../framer-motion-internals.ts';
+export { type DragControlOptions, DragControls, } from '../framer-motion-internals.ts';
+/** Motion's useDragControls(): one DragControls per owner, created once */
+export declare const createDragControls: () => DragControls;
+//# sourceMappingURL=drag-controls.d.ts.map

package/declarations/gestures/drag-controls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drag-controls.d.ts","sourceRoot":"","sources":["../../src/gestures/drag-controls.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAE7D,OAAO,EACL,KAAK,kBAAkB,EACvB,YAAY,GACb,MAAM,+BAA+B,CAAC;AAEvC,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,QAAO,YAAkC,CAAC"}

package/declarations/gestures/drag-gesture.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Motion's drag feature, with the two places glimmer-motion's drag differs
+ * from React's. Everything else is upstream's.
+ */
+import type { VisualElement } from 'motion-dom';
+import { DragGesture } from '../framer-motion-internals.ts';
+export declare class GlimmerDragGesture extends DragGesture {
+    constructor(node: VisualElement<HTMLElement>);
+    /**
+     * Upstream keeps the pan session alive when a component unmounts mid-drag,
+     * because in React 19 a list reorder can unmount and remount a component
+     * while the gesture is still live. Glimmer has no such reconciliation: a
+     * keyed `{{#each}}` moves a node rather than tearing it down and building it
+     * again, so an unmount here means the element is gone and the gesture has
+     * nothing left to move.
+     *
+     * Upstream's guard skips `cancel()`, and `cancel()` is what releases the
+     * module-global `setDragLock`. If the pointerup never arrives (the element
+     * was removed mid-gesture, the tab lost the pointer, a module reloaded), the
+     * lock is held forever and every later drag on the page bails before
+     * `onDragStart`. The pan session still moves elements, so dragging looks
+     * fine while `onDragStart` / `onDragEnd` silently stop firing.
+     *
+     * `cancel()` ends the session, releases the lock and clears `whileDrag`.
+     */
+    unmount(): void;
+}
+//# sourceMappingURL=drag-gesture.d.ts.map

package/declarations/gestures/drag-gesture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drag-gesture.d.ts","sourceRoot":"","sources":["../../src/gestures/drag-gesture.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGhD,OAAO,EAEL,WAAW,EAEZ,MAAM,+BAA+B,CAAC;AAkDvC,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,IAAI,EAAE,aAAa,CAAC,WAAW,CAAC;IAK5C;;;;;;;;;;;;;;;;OAgBG;IACM,OAAO;CAKjB"}

package/declarations/gestures/lock-select.d.ts

@@ -0,0 +1,3 @@
+export declare function lockTextSelect(): void;
+export declare function unlockTextSelect(): void;
+//# sourceMappingURL=lock-select.d.ts.map

package/declarations/gestures/lock-select.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock-select.d.ts","sourceRoot":"","sources":["../../src/gestures/lock-select.ts"],"names":[],"mappings":"AAQA,wBAAgB,cAAc,SAa7B;AAED,wBAAgB,gBAAgB,SAc/B"}

package/declarations/gestures/transform-page-point.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Motion's correctParentTransform / transformViewBoxPoint (utils/transform-rotated-parent.ts,
+ * utils/transform-viewbox-point.ts), with the React ref replaced by an element or a {current} ref.
+ */
+type Point = {
+    x: number;
+    y: number;
+};
+type TransformPoint = (p: Point) => Point;
+type Ref<T> = T | {
+    current: T | null;
+} | null | undefined;
+/** pointer coordinates corrected for a parent with a CSS transform (rotation, scale, skew) */
+export declare function correctParentTransform(parentRef: Ref<Element>): TransformPoint;
+/** pointer coordinates scaled into an <svg>'s viewBox coordinate system */
+export declare function transformViewBoxPoint(svgRef: Ref<SVGSVGElement>): TransformPoint;
+export {};
+//# sourceMappingURL=transform-page-point.d.ts.map

package/declarations/gestures/transform-page-point.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform-page-point.d.ts","sourceRoot":"","sources":["../../src/gestures/transform-page-point.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,KAAK,KAAK,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACtC,KAAK,cAAc,GAAG,CAAC,CAAC,EAAE,KAAK,KAAK,KAAK,CAAC;AAC1C,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG;IAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAAC;AAM3D,8FAA8F;AAC9F,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,GACtB,cAAc,CAiBhB;AA0BD,2EAA2E;AAC3E,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,GAAG,CAAC,aAAa,CAAC,GACzB,cAAc,CAuBhB"}