@maccesar/titools 4.17.1 → 4.19.0

package/skills/purgetss/references/animation-advanced.md

@@ -1,6 +1,6 @@
 # PurgeTSS Animation -- Advanced Reference
 
-Property inheritance, timing/utility classes, utility functions, implementation rules, and complex UI examples.
+Runtime property forwarding, timing/utility classes, utility functions, implementation rules, and complex UI examples.
 
 For core animation methods (play, toggle, apply, open, close, draggable, undraggable, detectCollisions, sequence, swap, pulse, shake, snapTo, reorder, transition), see [animation-system.md](./animation-system.md).
 
@@ -9,18 +9,42 @@ For core animation methods (play, toggle, apply, open, close, draggable, undragg
 <!-- TOC-START -->
 ## Contents
 
-- [Property Inheritance from the Animation Object](#property-inheritance-from-the-animation-object)
+- [Runtime Property Forwarding](#runtime-property-forwarding)
+  - [Forwarding and Overrides](#forwarding-and-overrides)
 - [Timing and Utility Classes](#timing-and-utility-classes)
+  - [anchorPoint / origin-* Classes](#anchorpoint--origin--classes)
+  - [autoreverse](#autoreverse)
+  - [Curve Classes](#curve-classes)
+  - [delay-*](#delay-)
+  - [duration-*](#duration-)
+  - [repeat-*](#repeat-)
+  - [rotate-* and -rotate-*](#rotate--and--rotate-)
+  - [scale-*](#scale-)
+  - [Snap Classes](#snap-classes)
+  - [keep-z-index](#keep-z-index)
+  - [Drag Type](#drag-type)
+  - [Opacity and Visibility Utilities](#opacity-and-visibility-utilities)
+  - [zoom-in-* / zoom-out-*](#zoom-in---zoom-out-)
 - [Utility Functions](#utility-functions)
-- [Implementation Rules](#implementation-rules)
-- [Method Implementation Template](#method-implementation-template)
+  - [deviceInfo()](#deviceinfo)
+  - [saveComponent({ source, directory })](#savecomponent-source-directory-)
+- [Runtime Implementation Rules](#runtime-implementation-rules)
+  - [Transform conversion](#transform-conversion)
+  - [State and children](#state-and-children)
+  - [Arrays and callbacks](#arrays-and-callbacks)
+  - [Position and drag state](#position-and-drag-state)
+  - [Android position consolidation](#android-position-consolidation)
+  - [Transition state](#transition-state)
+  - [Cleanup limitations](#cleanup-limitations)
 - [Complex UI Example](#complex-ui-example)
+  - [XML](#xml)
+  - [Controller](#controller)
 
 <!-- TOC-END -->
 
-## Property Inheritance from the Animation Object
+## Runtime Property Forwarding
 
-All methods in the Animation module inherit properties from the `<Animation>` object's classes. You configure animation behavior in XML and it applies to every method call.
+The constructor keeps the resolved `<Animation>` properties as its base object. Most helpers spread that object into `Ti.UI.createAnimation()` before adding their own fields. This forwards native values such as `duration`, `delay`, `curve`, `opacity`, or `backgroundColor`, but it does not guarantee that every Titanium property is meaningful for every helper.
 
 When you declare an Animation object with utility classes:
 
@@ -28,38 +52,22 @@ When you declare an Animation object with utility classes:
 <Animation id="myAnim" module="purgetss.ui" class="duration-150 delay-100 curve-animation-ease-out" />
 ```
 
-The parsed properties (`duration: 150`, `delay: 100`, `curve: EASE_OUT`) are stored in the internal `args` object. Each method reads from `args` as its default values.
+In Classic, the equivalent values are passed directly to `createAnimation()`; see [purgetss-ui-classic.md](./purgetss-ui-classic.md).
 
-### Inheritance Matrix
+### Forwarding and Overrides
 
-| Property | play/toggle | open/close | apply | sequence | swap | reorder | snapTo | shake | pulse | transition |
-| --- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
-| `duration` | Y | Y | -- | Y | Y | Y | Y | Y (div6) | Y | Y |
-| `delay` | Y | Y | -- | Y | Y | Y | Y | Y | Y | Y |
-| `curve` | Y | Y | -- | Y | Y | Y | Y | fixed | fixed | Y |
-| `autoreverse` | Y | Y | -- | Y | -- | -- | -- | fixed | fixed | -- |
-| `repeat` | Y | Y | -- | Y | -- | -- | -- | fixed | param | -- |
-
-**Legend:**
-- **Y** = inherited from Animation object
-- **--** = not applicable to this method
-- **fixed** = uses internal fixed values (`shake`: `autoreverse: true`, `repeat: 3`, `curve: EASE_IN_OUT`; `pulse`: `autoreverse: true`, `curve: EASE_IN_OUT`)
-- **param** = controlled by method parameter (`pulse` `count` sets the repeat value)
-- **(div6)** = `shake` divides the inherited duration by 6 for each oscillation cycle
-
-### Fallback Defaults
-
-When a property is not set on the Animation object and no explicit parameter is passed:
-
-| Property | `swap` / `reorder` / `snapTo` | `shake` |
-| --- | :---: | :---: |
-| `duration` | 200ms | 400ms |
-| `delay` | 0ms | 0ms |
-| `curve` | `EASE_IN_OUT` | `EASE_IN_OUT` (fixed) |
-
-### Explicit Parameters Take Precedence
+| Method | Forwarded base values | Forced or computed values |
+| --- | --- | --- |
+| `play` / `toggle` / `open` / `close` | Base object plus active state | Active-state transform |
+| `apply` | Base object plus active state | Applies immediately rather than creating native motion |
+| `sequence` | Same state values as `play` | Serial start order |
+| `swap` | Base object | Destination position; source identity transform |
+| `pulse` | Base object | Transform fallback, `autoreverse`, `repeat`, and curve |
+| `shake` | Non-overridden base values | Transform, divided duration, `autoreverse`, `repeat`, and curve |
+| `snapTo` / `reorder` | Base object | Destination position and identity transform |
+| `transition` | Base object | Combined layout transform and optional size/opacity |
 
-An explicit value passed as a method parameter always overrides the inherited value:
+Method-specific assignments are appended after the spread and therefore win on duplicate keys. The method parameters are feature-specific rather than alternative timing values:
 
 ```javascript
 // All timing controlled by the Animation object's classes
@@ -70,6 +78,8 @@ $.myAnim.snapTo($.card, targets)
 $.myAnim.transition(views, fanOutLayout)
 ```
 
+There is no shared `200ms`/`0ms`/`EASE_IN_OUT` fallback for `swap`, `snapTo`, `reorder`, or `transition`. Configure timing on the Animation object when predictable visible motion matters. Only `shake` computes `(duration ?? 400) / 6`; `pulse` supplies a default scale of `1.2`. Both helpers force ease-in-out.
+
 ---
 
 ## Timing and Utility Classes
@@ -182,12 +192,12 @@ Control how draggable views behave when dropped. All are **off by default**.
 | `snap-back-false` | `{ animationProperties: { snap: { back: false } } }` | Disables snap-back |
 | `snap-center` | `{ animationProperties: { snap: { center: true } } }` | Auto-centers on target |
 | `snap-center-false` | `{ animationProperties: { snap: { center: false } } }` | Disables snap-center |
-| `snap-magnet` | `{ animationProperties: { snap: { magnet: true } } }` | (Planned) Magnetic attraction |
-| `snap-magnet-false` | `{ animationProperties: { snap: { magnet: false } } }` | Disables snap-magnet |
+
+Generated utility inventories may still contain `snap-magnet` names, but the current `purgetss.ui` runtime never reads `animationProperties.snap.magnet`. Do not use or recommend those classes as working drag behavior.
 
 ### keep-z-index
 
-Prevents the drag system from auto-promoting the dragged view's z-index. Useful when using `transition` presets where z-order is part of the layout.
+Prevents the drag system from promoting the active view on touch start. It does not prevent `draggable(array)` from first assigning each view `zIndex` from its array position, and `swap()` restores z-order from the current draggable registry rather than arbitrary original values.
 
 ```css
 '.keep-z-index': { animationProperties: { keepZIndex: true } }
@@ -234,236 +244,93 @@ The module exports helper functions alongside the Animation component:
 
 ### deviceInfo()
 
-Logs detailed platform and display information to the console. Works in both Alloy and Classic Titanium projects.
+Logs platform and display information and returns `undefined`. It includes `xdpi` and `ydpi` only on Android. Its tablet flag currently recognizes iPad only, so Android tablets are reported as handheld.
 
 ```javascript
 const { deviceInfo } = require('purgetss.ui')
 deviceInfo()
 ```
 
+Classic loads the generated file with `require('lib/purgetss.ui')`.
+
 ### saveComponent({ source, directory })
 
-Saves a snapshot of a view as a PNG to the photo gallery.
+Calls `source.toImage()`, creates an MD5-based PNG filename, writes it to `directory` (default: `Ti.Filesystem.tempDirectory`), and then invokes `Ti.Media.saveToPhotoGallery()`. It returns `undefined` and has no completion or error callback.
 
 ```javascript
 const { saveComponent } = require('purgetss.ui')
-saveComponent({ source: $.myView, directory: 'screenshots' })
-```
-
----
-
-## Implementation Rules
-
-Rules that every method in the Animation module must follow. They keep behavior consistent with the declarative model of PurgeTSS.
-
-### Rule 1: Inherit from the `<Animation />` object via `...args`
-
-Every method MUST inherit all properties from the Animation object by spreading `args`. Never cherry-pick individual properties.
-
-The `<Animation />` object is the single source of truth for animation behavior. When a developer declares:
-
-```xml
-<Animation id="myAnim" module="purgetss.ui" class="curve-animation-ease-out opacity-50 delay-100 duration-300" />
+saveComponent({ source: $.myView, directory: Ti.Filesystem.applicationDataDirectory })
 ```
 
-Every property -- timing AND visual -- is available in `args` and MUST be inherited by all methods.
-
-```javascript
-// CORRECT -- inherits everything, method-specific props override
-view.animate({ ...args, left: destLeft, top: destTop, transform: Ti.UI.createMatrix2D() })
-
-// WRONG -- cherry-picks individual properties, breaks if new ones are added
-view.animate({ duration: args.duration, delay: args.delay, left: destLeft, top: destTop })
-```
-
-This is the same pattern used by the core `playView` function:
-
-```javascript
-const animation = Ti.UI.createAnimation(args)
-view.animate(animation)
-```
-
-If a developer adds `opacity-50` to their `<Animation>`, they expect ALL methods to animate opacity, not just `play`.
-
-### Rule 2: Override by position, not by exclusion
-
-If a method needs fixed values for specific properties, they go AFTER `...args` to override. Never filter or exclude properties from args.
+Check or request photo-gallery permission before calling it. On iOS, declare the photo-library add usage description required by Titanium. Classic uses `require('lib/purgetss.ui')`; see [purgetss-ui-classic.md#runtime-utilities](./purgetss-ui-classic.md#runtime-utilities).
 
-```javascript
-// CORRECT -- shake: inherits everything, then overrides what it needs
-view.animate({
-  ...args,
-  transform: Ti.UI.createMatrix2D().translate(intensity, 0),
-  duration: Math.round((args.duration ?? 400) / 6),
-  autoreverse: true,
-  repeat: 3,
-  curve: Ti.UI.ANIMATION_CURVE_EASE_IN_OUT
-})
-
-// WRONG -- filters args, only picks what it thinks it needs
-view.animate({
-  duration: args.duration,
-  transform: Ti.UI.createMatrix2D().translate(intensity, 0),
-  autoreverse: true,
-  repeat: 3
-})
-```
+---
 
-Properties declared later in the object literal override earlier ones:
+## Runtime Implementation Rules
 
-```javascript
-// If args = { duration: 300, opacity: 0.5, curve: EASE_OUT }
-view.animate({
-  ...args,        // duration: 300, opacity: 0.5, curve: EASE_OUT
-  duration: 50,   // overrides to 50
-  curve: EASE_IN  // overrides to EASE_IN
-})
-// Result: { duration: 50, opacity: 0.5, curve: EASE_IN }
-// opacity 0.5 is preserved from args -- not lost by filtering
-```
+These are observable rules of the generated module. Use them to diagnose surprising output; they are not a template or promise for future extension methods.
 
-### Rule 3: No timing parameters in method signatures
+### Transform conversion
 
-The existing core methods (`play`, `open`, `close`, `apply`, `sequence`) do NOT accept `duration`, `delay`, or `curve` as parameters. New methods MUST follow the same pattern. Only parameters specific to the method's unique functionality are allowed.
+At construction time, top-level `scale`, `rotate`, and `anchorPoint` are converted into one `Ti.UI.Matrix2D` and removed from the base object. Separate matrices are prepared for `animationProperties.open` and `.close`. `pulse`, `shake`, `swap`, `snapTo`, `reorder`, and `transition` may replace or reset that transform, so a position helper does not promise to preserve it.
 
-```javascript
-// CORRECT -- only method-specific parameters
-animationView.swap = (view1, view2) => {
-animationView.reorder = (views, newOrder) => {
-animationView.shake = (view, intensity = 10) => {
-animationView.snapTo = (view, targets) => {
-animationView.pulse = (view, count = 1) => {
-
-// WRONG -- timing parameters belong in the <Animation /> object
-animationView.swap = (view1, view2, duration) => {
-animationView.shake = (view, intensity, duration) => {
-```
+### State and children
 
-Users control timing declaratively:
+`play()`, `toggle()`, `apply()`, and `sequence()` toggle internal open/close state. `open()` and `close()` set it explicitly. The active state is merged into the current base object when `animationProperties` exists.
 
-```xml
-<!-- Fast swap -->
-<Animation id="fastSwap" module="purgetss.ui" class="duration-75" />
+After a top-level `play`, `toggle`, `open`, or `close`, `animationProperties.complete` starts as a second animation. `apply()` applies `complete` immediately. The public callback belongs to the base play/apply operation; it does not wait for the second top-level `complete` animation.
 
-<!-- Slow swap with delay -->
-<Animation id="slowSwap" module="purgetss.ui" class="delay-200 duration-500" />
-```
+For each direct child with an active state, merge precedence is:
 
-```javascript
-// Same method call, different behavior -- controlled by XML
-$.fastSwap.swap($.card1, $.card2)
-$.slowSwap.swap($.card1, $.card2)
-```
+1. Parent `animationProperties.children`.
+2. Child `animationProperties.child`.
+3. Child `animationProperties.open`, `.close`, or `.complete`.
 
-### Rule 4: Consolidate state with `applyProperties` post-animation
+Later objects win. Only direct children of the target are considered.
 
-After animating position (`left`/`top`), ALWAYS consolidate with `applyProperties` in the callback so the final state is real (not just visual via transform).
+### Arrays and callbacks
 
-```javascript
-// CORRECT -- consolidates after animation
-view.animate({
-  ...args, left: destLeft, top: destTop, transform: Ti.UI.createMatrix2D()
-}, () => {
-  view.applyProperties({ left: destLeft, top: destTop, transform: Ti.UI.createMatrix2D() })
-})
-
-// WRONG -- animation ends but view's actual properties are stale
-view.animate({
-  ...args, left: destLeft, top: destTop, transform: Ti.UI.createMatrix2D()
-})
-```
+`play()`, `open()`, `close()`, and `apply()` accept one view or an array. Array callbacks run once per view and include `index`, `total`, and `getTarget()`. The configured base delay accumulates for successive views. `sequence()` waits for each native completion and invokes its callback once after the final view; an empty array never invokes it.
 
-On iOS, dragging uses `transform.translate()` -- the view's `left`/`top` properties don't change. `applyProperties` ensures the view's actual properties match the visual position and the transform is reset to identity.
+The callback is a new object containing selected native primitives plus PurgeTSS metadata. It is not the original Titanium event.
 
-### Rule 5: Track position with `_origin*` properties
+### Position and drag state
 
-Methods that move position (`swap`, `reorder`, `snapTo`, and future methods like `slideTo`) MUST update `_originTop`/`_originLeft` after the animation so that subsequent drag/swap operations work correctly.
+`swap()`, `snapTo()`, and `reorder()` persist destinations with `applyProperties()` and update private origin fields. They fall back to rendered `rect` coordinates, so call them only after layout.
 
-```javascript
-// CORRECT -- updates origin tracking
-view.animate({
-  ...args, left: destLeft, top: destTop, transform: Ti.UI.createMatrix2D()
-}, () => {
-  view.applyProperties({ left: destLeft, top: destTop, transform: Ti.UI.createMatrix2D() })
-})
-
-view._originTop = destTop
-view._originLeft = destLeft
-```
+Drag precedence is precise:
 
-How `_origin*` works:
-- `_originTop`/`_originLeft` represent the view's "logical grid position"
-- `swap` reads from `view._originTop ?? view.top` -- falls back to the actual `top` if no origin is set
-- `onTouchStart` in the drag handler saves the current `top`/`left` as `_origin*` for bounce-back
-- `undraggable` cleans up all `_origin*` properties
+- Constructor bounds are the base; `view.bounds` overrides individual edges.
+- Axis restriction comes only from `view.constraint`.
+- `view.draggingType` overrides constructor `draggingType`.
+- Constructor `draggable.drag/drop` is merged with `view.draggable.drag/drop`; view properties win.
+- Every resolved drag/drop property is forwarded to Titanium.
+- `snap.center` invokes `snapTo()` after a valid drop; `snap.back` returns a missed drop to its captured origin.
+- No `snap.magnet` behavior exists.
 
-### Rule 6: Consolidate Android drag position before drop animations
+Collision detection uses the dragged view's center. On release, the last non-null hover target is a fallback when the final hit test returns `null`.
 
-On Android, drag uses `animate({ duration: 0 })` which is asynchronous -- the last frame may still be in-flight when `touchend` fires. Before starting any drop animation on Android, consolidate the view's position with `applyProperties`:
+`draggable(array)` immediately assigns each view `zIndex` from its array index. `keepZIndex` only disables later touch-start promotion. `swap()` restores z-order by the current draggable-registry order, not by arbitrary values present before registration.
 
-```javascript
-if (!params.isIOS) {
-  draggableView.applyProperties({
-    top: draggableView._visualTop ?? draggableView.top,
-    left: draggableView._visualLeft ?? draggableView.left
-  })
-}
-```
-
-This applies to both the snap path and the bounce-back path in `onTouchEnd`. iOS does not need this because drag uses synchronous `transform.translate()`.
+### Android position consolidation
 
-**Collision fallback on drop:** During drag, `checkCollision` runs on every `touchmove`. When the user releases while still in motion, the drag center may exit the target between the last `touchmove` and `touchend`. The module tracks `lastKnownTarget` and uses it as fallback when `checkCollision` returns null on drop.
+Android drag uses zero-duration native animations. At touch end, when translation state exists, the runtime consolidates `translation`, `rotate`, `scale`, and an equivalent `Matrix2D` before collision, snap, or drop callbacks. It does not consolidate only `top` and `left`. iOS uses synchronous property application for standard dragging and a separate transformed-view path.
 
-### Rule 7: Clean up in `undraggable`
-
-Every internal property added to views MUST be cleaned up in `undraggable`:
-
-| Property | Set by | Purpose |
-| --- | --- | --- |
-| `_originTop` / `_originLeft` | `swap`, `reorder`, `snapTo`, `onTouchStart` | Logical position tracking |
-| `_visualTop` / `_visualLeft` | `handleTouchMove` | Visual position during drag |
-| `_dragListeners` | `makeViewsDraggable` | Touch event listener references |
-| `_collisionEnabled` | `detectCollisions` | Collision detection flag |
-| `_wasDragged` | `onTouchStart` / `handleTouchMove` | Drag detection flag |
-| `_bouncingBack` | `onTouchEnd` (bounce-back) | Prevents origin capture during mid-animation; `swap` cancels it before animating |
+### Transition state
 
-When adding a new method that stores internal state on views, add the cleanup to `undraggable`:
+`transition()` builds one matrix per view from translation, rotation, and scale, applies a supplied `zIndex` before animation, and can animate width, height, and opacity.
 
-```javascript
-animationView.undraggable = (_views) => {
-  const arr = Array.isArray(_views) ? _views : [_views]
-  arr.forEach(view => {
-    // ... existing cleanup ...
-    delete view._newProperty  // ADD cleanup for any new internal property
-  })
-}
-```
+Without a matching layout, a view fades out, receives `zIndex: 0`, and has touch disabled. iOS preserves its last transform; Android resets transform, translation, rotation, and scale. A later layout fades the view back in. Completion forces `touchEnabled: true` for every matched view, so reapply `false` for intentionally non-interactive views.
 
----
+### Cleanup limitations
 
-## Method Implementation Template
+`undraggable()` removes the latest stored touch/orientation listeners, the first matching draggable and collision registrations, and most private drag state. Current limitations require application discipline:
 
-When creating a new method, follow this template:
+- `draggable()` does not deduplicate. Repeated registration creates extra listeners and entries that one cleanup call cannot fully remove.
+- `_wasDragged` remains on the view after `undraggable()`.
+- `detectCollisions()` retains non-null callbacks on the animation object; passing `null` later does not clear them.
 
-```javascript
-animationView.newMethod = (view, specificParam = defaultValue) => {
-  if (params.debug) { console.log('') }
-  logger('`newMethod` method called on: ' + params.id)
-  if (!view) { return notFound() }
-
-  view.animate({
-    ...args,                          // Rule 1: inherit all from <Animation />
-    specificProp: computedValue,      // Rule 2: override AFTER ...args
-  }, () => {
-    view.applyProperties({ ... })    // Rule 4: consolidate state
-  })
-
-  view._originTop = newTop           // Rule 5: track position (if applicable)
-  view._originLeft = newLeft
-}
-// Rule 3: no timing params in signature
-// Rule 7: add cleanup to undraggable (if new internal state)
-```
+Register each view once. On window close, call `undraggable()` for draggable views and registered collision targets, remove application-owned listeners, and release callbacks and animation references that are no longer needed. Do not make application code depend on private underscore fields.
 
 ---
 

package/skills/purgetss/references/animation-system.md

@@ -27,6 +27,8 @@
 
 PurgeTSS includes an Animation module for 2D Matrix animations and transformations. It works on single elements, arrays of elements, or individual children of an element.
 
+The XML and `$.*` examples in this file are for Alloy. Titanium Classic uses the same generated runtime through JavaScript objects; see [purgetss-ui-classic.md](./purgetss-ui-classic.md) for the Classic installation path, factory API, method contracts, and lifecycle rules.
+
 The Animation object describes an animation in a few ways:
 - A single-phase animation with an end state
 - A multi-phase animation using the `open`, `close`, and `complete` modifiers
@@ -62,13 +64,13 @@ You can use any position, size, color, transformation, and opacity classes from
 | `open` | `open(views, cb)` | Explicitly run the opening animation (no toggle) |
 | `close` | `close(views, cb)` | Explicitly run the closing animation (no toggle) |
 | `draggable` | `draggable(views)` | Make views draggable via touch events |
-| `undraggable` | `undraggable(views)` | Remove draggable behavior and clean up all listeners |
+| `undraggable` | `undraggable(views)` | Remove the module-owned drag listeners and most private drag state |
 | `detectCollisions` | `detectCollisions(views, dragCB, dropCB)` | Enable collision detection with hover/drop callbacks |
 | `sequence` | `sequence(views, cb)` | Animate views one after another (sequential, not parallel) |
 | `swap` | `swap(view1, view2)` | Animate two views exchanging positions |
 | `pulse` | `pulse(view, count)` | Scale-up-and-back animation (default count=1) |
 | `shake` | `shake(view, intensity)` | Horizontal shake for feedback (default intensity=10) |
-| `snapTo` | `snapTo(view, targets)` | Snap view to nearest target by center distance; returns matched target or null |
+| `snapTo` | `snapTo(view, targets)` | Snap to the nearest target; returns it immediately, `null` if none qualifies, or `undefined` for a missing source |
 | `reorder` | `reorder(views, newOrder)` | Animate views to new positions by index mapping |
 | `transition` | `transition(views, layouts)` | Multi-view layout transitions using Matrix2D (translate, rotate, scale) |
 
@@ -82,7 +84,7 @@ The `play`, `toggle`, `open`, `close`, `apply`, and `sequence` methods accept an
 | --- | --- |
 | `open:` | Properties applied during open state |
 | `close:` | Properties applied during close state |
-| `complete:` | Additional properties applied after an open animation finishes |
+| `complete:` | Additional properties applied after the active `play`/`toggle`/`open`/`close` state, or immediately after `apply` |
 | `children:` | Global properties for all children of a View |
 | `child:` | Individual properties for specific children |
 | `bounds:` | Drag boundaries within parent |
@@ -127,7 +129,7 @@ First call applies `open:` properties; next call applies `close:` properties; co
 
 ### `complete` Modifier
 
-Applies additional properties after an `open` animation finishes:
+Applies additional properties after the active state finishes. With `play`, `toggle`, `open`, or `close`, it starts a second native animation; with `apply`, it is applied immediately:
 
 ```xml
 <Animation module="purgetss.ui" id="myAnimationOpen"
@@ -147,6 +149,8 @@ $.myAnimation.play([$.view1, $.view2, $.view3])
 
 The callback fires once per view. Use `e.index` and `e.total` to track progress.
 
+Array playback starts all views without waiting for the previous completion. The configured base delay is increased cumulatively for each successive view. Use `sequence()` when each view must finish before the next begins.
+
 ---
 
 ## Callback Event Object
@@ -278,7 +282,7 @@ A blank or existing Animation object can be reused. When used with an array, zIn
 
 - **Global modifiers** on the Animation object apply to all views
 - **Local modifiers** on individual views override globals
-- While dragging, `size`, `scale`, and `anchorPoint` transformations are **not** applied
+- All properties in the resolved `drag` or `drop` object are forwarded to Titanium, including size, transform, and anchor-point properties
 
 ```xml
 <Animation id="draggableAnimation" module="purgetss.ui" class="drag:duration-100 drag:opacity-50 drop:opacity-100" />
@@ -312,14 +316,16 @@ Limits movement within the parent. Local on the view or global on the Animation
 
 ## The `undraggable` Method
 
-Removes draggable behavior and cleans up all listeners from one or more views.
+Removes the current module-owned draggable behavior from one or more views.
 
 ```javascript
 $.draggableAnimation.undraggable($.card)
 $.draggableAnimation.undraggable([$.card1, $.card2, $.card3])
 ```
 
-Removes: `touchstart`/`touchend`/`touchmove` listeners, `Ti.Gesture.orientationchange` listener, collision detection registry entries, and internal properties (`_originTop`, `_originLeft`, `_visualTop`, `_visualLeft`, `_collisionEnabled`, `_dragListeners`, `_wasDragged`, `_bouncingBack`).
+It removes the stored `touchstart`/`touchend`/`touchmove` listeners, the stored `Ti.Gesture.orientationchange` listener, the first matching draggable/collision registry entries, and most private position/collision fields. The current runtime does **not** delete `_wasDragged`.
+
+Register each view only once. `draggable()` does not deduplicate registrations: repeated calls add listeners and registry entries, while one `undraggable()` call removes only the latest stored listener set and the first matching entries. `detectCollisions()` also retains the last non-null callbacks on the Animation object; passing `null` later does not clear them.
 
 **Use cases:** Lock a piece after correct placement, toggle edit/presentation mode, cleanup on window close (prevents memory leaks from global `orientationchange` listener).
 
@@ -418,6 +424,7 @@ $.myAnimation.sequence(views, callback)
 - The `open`/`close` state is toggled once for the entire sequence
 - Each view fully completes before the next starts
 - The callback fires once after the last view finishes
+- An empty array starts nothing and does not invoke the callback
 
 ### Onboarding Reveal Example
 
@@ -448,9 +455,9 @@ $.myAnimation.swap(view1, view2)
 ```
 
 **Behavior:**
-- Inherits `duration`, `delay`, `curve` from Animation object. Fallback: **200ms**, **0ms**, **EASE_IN_OUT**
-- Handles iOS transform reset automatically
-- Temporarily elevates z-index; restores after completion
+- Forwards the Animation object's native properties; there is no shared duration, delay, or curve fallback
+- Resets the source transform while persisting the exchanged positions
+- Temporarily elevates z-index; then assigns z-index from the current draggable-registry order rather than restoring arbitrary original values
 - Updates `_originLeft`/`_originTop` for subsequent drag operations
 - **Automatic position normalization**: no explicit `top`/`left` needed -- resolved via `view.rect`
 - **Bounce-back safe**: completes any in-progress bounce-back before swapping
@@ -514,7 +521,7 @@ $.myAnimation.shake(view, intensity)
 | `view` | `View` | -- | The view to shake |
 | `intensity` | `Number` | `10` | Horizontal displacement in pixels |
 
-- `duration`: inherited, divided by 6 for each shake cycle. Fallback: 400ms
+- `duration`: inherited, or `400ms` when absent, then divided by 6 for each shake phase
 - `delay`: inherited, applied before shake starts
 - `curve`: always `EASE_IN_OUT` (fixed)
 - `autoreverse` and `repeat`: always `true` and `3` (fixed)
@@ -528,14 +535,14 @@ $.emailField.applyProperties({ borderColor: '#ef4444' })
 
 ## The `snapTo` Method
 
-Snaps a view to the nearest target by center-to-center Euclidean distance. Returns the matched target or `null`.
+Snaps a view to the nearest target by center-to-center Euclidean distance. It returns the matched target immediately, `null` when no target can be selected, or `undefined` for a missing source; the return does not mean the animation has completed.
 
 ```javascript
 const matched = $.myAnimation.snapTo(view, targets)
 ```
 
-- Inherits `duration`, `delay`, `curve`. Fallback: **200ms**, **0ms**, **EASE_IN_OUT**
-- Handles iOS transform reset; updates `_originLeft`/`_originTop`
+- Forwards the Animation object's native properties; there is no shared duration, delay, or curve fallback
+- Resets the moved view's transform and updates `_originLeft`/`_originTop`
 - Automatic position normalization
 
 ### Puzzle Game with Collision Detection
@@ -567,7 +574,7 @@ $.myAnimation.reorder(views, newOrder)
 
 - `newOrder` maps current index to new position: `[2, 1, 0]` reverses, `[1, 2, 0]` rotates
 - Length must match `views` length
-- Inherits `duration`, `delay`, `curve`. Fallback: **200ms**, **0ms**, **EASE_IN_OUT**
+- Forwards the Animation object's native properties; there is no shared duration, delay, or curve fallback
 - Automatic position normalization
 
 ```javascript
@@ -604,7 +611,9 @@ $.myAnimation.transition(views, layouts)
 - Each view gets a single `Ti.UI.createAnimation()` with combined `Matrix2D` transform
 - All animations launch simultaneously
 - `zIndex` applied synchronously before animation starts
-- **Mismatched lengths**: extra views fade out; extra layouts ignored; faded views fade back in when given a layout entry
+- **Mismatched lengths**: extra views fade to opacity `0`, receive `zIndex: 0`, and have touch disabled; extra layouts are ignored; hidden views fade back in and regain touch when later given a layout entry
+- iOS preserves the last transform of a hidden view. Android resets its transform, translation, rotation, and scale
+- A matched layout's completion handler forces `touchEnabled: true`; reapply `false` afterward for a view that must remain non-interactive
 
 ### Reusable Presets
 
@@ -639,7 +648,7 @@ function doStack() { $.galleryAnim.transition(photos, stack) }
 $.galleryAnim.draggable(photos)  // photos keep rotation/scale while dragging
 ```
 
-`keep-z-index` preserves the layout order during drag.
+`keep-z-index` prevents touch-start promotion during drag. It does not prevent `draggable(array)` from first assigning each view `zIndex` from its array index.
 
 ### Mac Catalyst Note