@maccesar/titools 4.18.0 → 4.20.0

package/skills/purgetss/references/custom-fonts.md

@@ -178,7 +178,7 @@ After `purgetss build-fonts`, the generated `fonts.tss` includes the family clas
 
 Two optional flags adjust what `build-fonts` generates:
 
-- `-m, --module`: generates a CommonJS module in `app/lib/purgetss.fonts.js` (Alloy) or `Resources/lib/purgetss.fonts.js` (Classic) that exposes each icon's Unicode string to JavaScript.
+- `-m, --module`: generates a CommonJS module in `app/lib/purgetss.fonts.js` (Alloy) or `Resources/lib/purgetss.fonts.js` (Classic). Its `families` object exposes the PostScript name of every processed TTF/OTF; icon CSS additionally populates `icons` with Unicode strings.
 - `-f, --font-class-from-filename`: uses the font's filename as the font class name and icon prefix instead of the font family name. Useful when you want shorter prefixes. Replaces the old `-p` flag.
 
 ### Using `--module`
@@ -190,7 +190,7 @@ $ purgetss build-fonts --module
 $ purgetss bf -m
 ```
 
-To avoid prefix conflicts between libraries, each icon keeps its prefix as a nested object. Both `icons` and `families` are exported:
+The module is generated for text-only font collections too. By default, every TTF/OTF contributes a camel-cased PostScript-name key to `families`; with `--font-class-from-filename`, that key comes from the filename instead. Icon CSS can add a shorter family alias and a nested `icons` map. Both singular and plural export names remain available.
 
 `app/lib/purgetss.fonts.js` (Alloy) or `Resources/lib/purgetss.fonts.js` (Classic)
 ```javascript
@@ -212,17 +212,40 @@ const icons = {
     // ...
   }
 };
+exports.icon = icons;
 exports.icons = icons;
 
 const families = {
+  'bevanItalic': 'Bevan-Italic',
+  'bevanRegular': 'Bevan-Regular',
+  'dancingScriptBold': 'DancingScript-Bold',
+  'dancingScriptMedium': 'DancingScript-Medium',
+  'dancingScriptRegular': 'DancingScript-Regular',
+  'dancingScriptSemiBold': 'DancingScript-SemiBold',
+  'mapIcons': 'map-icons',
+  'microns': 'microns',
   // map-icons/map-icons.css
   'mapIcon': 'map-icons',
   // microns/microns.css
   'mu': 'microns'
 };
+exports.family = families;
 exports.families = families;
 ```
 
+In Classic, load the generated file relative to `Resources/`:
+
+```javascript
+const customFonts = require('lib/purgetss.fonts')
+
+const heading = Ti.UI.createLabel({
+  text: 'Custom typography',
+  font: { fontFamily: customFonts.families.dancingScriptSemiBold, fontSize: 28 }
+})
+```
+
+See the complete [Classic module path table](./classic-projects.md#loading-generated-modules-in-classic).
+
 ### Using `--font-class-from-filename`
 
 When you want the class name and the icon prefix to come from the **filename** of the `.ttf` and `.css` instead of the font family, use `-f`.
@@ -282,14 +305,18 @@ const icons = {
     // ...
   }
 };
+exports.icon = icons;
 exports.icons = icons;
 
 const families = {
+  'map': 'map-icons',
+  'mic': 'microns',
   // map-icons/mp.css
   'mp': 'map-icons',
   // microns/mc.css
   'mc': 'microns'
 };
+exports.family = families;
 exports.families = families;
 ```
 

package/skills/purgetss/references/customization-deep-dive.md

@@ -50,12 +50,14 @@ module.exports = {
     }
   },
   brand: {
-    background: '#FFFFFF',   // inherited by every piece that doesn't set its own
-    confirmOverwrites: true, // prompt before overwriting files (set false to skip)
-    optimize: false,         // true = quantize the generated PNGs to a palette (lossy, ~71% smaller)
+    background: '#FFFFFF',      // inherited by every piece that doesn't set its own
+    artworkCornerRadius: '0%',  // rounded non-icon artwork: splashes, Feature Graphic and LaunchLogo
+    confirmOverwrites: true,    // prompt before overwriting files (set false to skip)
+    optimize: false,            // true = quantize the generated PNGs to a palette (lossy, ~71% smaller)
 
     // One block per piece. Artwork comes from purgetss/brand/logo-<piece>.{svg,png};
     // these keys are for numbers, colors and activation. Padding is never inherited.
+    // Only iosSplash, androidSplash, featureGraphic and launchLogo accept cornerRadius.
     icon:             { padding: '0%' },    // DefaultIcon.png + DefaultIcon-ios.png
     dark:             { background: null }, // DefaultIcon-Dark.png
     tinted:           {},                   // DefaultIcon-Tinted.png
@@ -65,7 +67,7 @@ module.exports = {
     featureGraphic:   { padding: '12%' },   // MarketplaceArtworkFeature.png (1024×500)
     adaptive:         { padding: '18%' },   // ic_launcher_{foreground,background,monochrome}.png × 5 + ic_launcher.xml
     legacyIcon:       { padding: '10%' },   // ic_launcher.png × 5
-    appicon:          {},                   // appicon.png (128×128)
+    appicon:          { padding: '10%' },   // appicon.png (128×128)
     androidSplash:    { padding: '26%' },   // assets/android/default.png + images/res-*/default.png × 11
 
     // Opt-in: inert until you edit the Android theme / FCM meta-data by hand.
@@ -73,14 +75,19 @@ module.exports = {
     notificationIcon: { enabled: false },   // drawable-*/ic_stat_notify.png × 5
     ninePatch:        { enabled: false }    // background.9.png (not implemented yet)
   },
+  // Sources in purgetss/images/ are 4x masters: a 1024px file yields
+  // 256 (mdpi/@1x), 384 (hdpi), 512 (xhdpi/@2x), 768 (xxhdpi/@3x), 1024 (xxxhdpi).
+  // There is no width to configure here — the source's own pixels decide.
+  // SVGs have no natural pixels; pin theirs in files: [] below.
   images: {
-    autoSync: true,          // false = SVG pipeline computes dims but doesn't write to images.files (v7.11.0)
-    quality: 85,             // JPEG/WebP/AVIF quality (0-100)
+    quality: 85,             // webp/jpeg/avif/tiff quality (0-100); PNG and GIF ignore it
     format: null,            // null = keep original; 'webp' | 'jpeg' | 'png' to convert every image
+    autoSync: true,          // false = SVG pipeline computes dims but doesn't write to images.files
     confirmOverwrites: true, // prompt before overwriting files (set false to skip)
-    files: []                // per-file overrides: [{ filename, width, height? }] (v7.11.0)
+    files: []                // per-file overrides: [{ filename: 'images/<sub>/<name>.<ext>', width, height? }]
     // Note: --width (v7.8.0) and --opacity / --padding / --output (v7.10.0) are CLI-only
-    //       by design — those decisions are per-asset, not project-wide.
+    //       by design — those decisions are per-asset, not project-wide. Since v7.17.0
+    //       writing any of them here aborts the run instead of being ignored.
   },
   theme: {
     extend: {}
@@ -98,14 +105,17 @@ The config file has four main sections: `purge`, `brand`, `images`, and `theme`.
 
 `brand:` and `images:` configure the matching CLI commands — see [CLI Commands: `brand`](./cli-commands.md#brand-command) and [CLI Commands: `images`](./cli-commands.md#images-command) for the full option lists. The rest of this page covers `purge` and `theme`.
 
-For `brand`, the structure is **one block per piece of artwork** (v7.13.0), each accepting the same four keys where they apply:
+For `brand`, the structure is **one block per piece of artwork** (v7.13.0), each accepting the same five keys where they apply:
 
 - `logo`: path to this piece's artwork, when it lives outside `purgetss/brand/`
 - `padding`: inset per side, as a number or a percentage string like `'19%'` — **never inherited**
+- `cornerRadius`: integer or percentage string from `0` through `50`, valid only in `iosSplash`, `androidSplash`, `featureGraphic`, and `launchLogo`
 - `background`: hex color, or `null` for transparent — inherited from `brand.background`
 - `enabled`: `false` turns a default piece off, `true` turns an opt-in piece on
 
-Plus `brand.background`, `brand.confirmOverwrites`, `brand.optimize`, `brand.logo` (the main logo) and `brand.monochromeLogo`.
+Plus `brand.background`, shared `brand.artworkCornerRadius` (default `'0%'`), optional splash-only `brand.splashCornerRadius`, `brand.confirmOverwrites`, `brand.optimize`, `brand.logo` (the main logo) and `brand.monochromeLogo`.
+
+Use flags for temporary artwork, geometry, the shared background, selection, activation, and optimization. Keep `confirmOverwrites`, permanent `enabled` values, and exceptional per-piece backgrounds in config. For radius, a piece-specific flag wins over the splash shortcut when applicable, then `--artwork-corner-radius`, piece config, `brand.splashCornerRadius` for splashes, `brand.artworkCornerRadius`, and `0%`.
 
 > **INFO — Older `brand:` blocks update themselves**
 > A `brand:` block written for an earlier PurgeTSS is rewritten **on disk** to this structure on the next run, carrying over every value that had been customized and printing each one it moved. Both earlier shapes are recognized: the original flat keys and the v7.7.0 grouped sections (`logos` / `padding` / `android` / `ios` / `colors`). This replaced the in-memory translation used from v7.10.2 to v7.12.1. A key that belongs to no structure at all — a typo — aborts the run with the list of valid ones instead of being ignored. See [App Icons & Branding → Older configs update themselves](./app-branding.md#older-configs-update-themselves).

package/skills/purgetss/references/dynamic-component-creation.md

@@ -2,7 +2,7 @@
 
 > **SCOPE NOTE**
 >
-> This reference covers dynamic component creation using **Alloy's `$.UI.create()` helper** and **`Alloy.createStyle()` + `applyProperties()`**, both combined with PurgeTSS utility classes. It is an Alloy + PurgeTSS integration guide, **not** documentation for the `purgetss.ui` native module (see [animation-system.md](./animation-system.md) and [animation-advanced.md](./animation-advanced.md) for that module).
+> This reference covers dynamic component creation using **Alloy's `$.UI.create()` helper** and **`Alloy.createStyle()` + `applyProperties()`**, both combined with PurgeTSS utility classes. It is an Alloy + PurgeTSS integration guide, **not** documentation for the `purgetss.ui` native module (see [animation-system.md](./animation-system.md) and [animation-advanced.md](./animation-advanced.md) for Alloy animation usage, or [purgetss-ui-classic.md](./purgetss-ui-classic.md) for the generated Classic runtime).
 >
 > For general Alloy controller and view patterns, refer to the `alloy-guides` and `alloy-howtos` skills.
 

package/skills/purgetss/references/icon-fonts.md

@@ -93,7 +93,7 @@ Each module exposes its existing icon lookup API plus a `families` object with `
 | `framework7icons` | `fontFamily` |
 
 ```javascript
-const fontAwesome = require('fontawesome')
+const fontAwesome = require('lib/fontawesome')
 
 const home = Ti.UI.createLabel({
   text: fontAwesome.icons.home,
@@ -104,6 +104,8 @@ const home = Ti.UI.createLabel({
 })
 ```
 
+All generated modules live under `Resources/lib/`, so use the pattern shown above: include `lib/` in the path and omit both `Resources/` and `.js`. See the centralized [Classic module path table](./classic-projects.md#loading-generated-modules-in-classic) for all four filenames.
+
 The direct alias and `families` values agree, for example `fontAwesome.solid === fontAwesome.families.solid`; `families.default` provides the library's default variant.
 
 ## Using icons in Alloy XML

package/skills/purgetss/references/installation-setup.md

@@ -61,7 +61,11 @@ When you run `purgetss` for the first time in your project, it does the followin
 
 ### 1. Auto-run Hook
 
-PurgeTSS adds a task in `alloy.jmk` to run `purgetss` every time you compile your app. Works well with `liveview`.
+PurgeTSS adds a task in `alloy.jmk` to run `purgetss` every time you compile your app. This works well with `liveview`.
+
+With the default synchronous method, the hook inherits PurgeTSS output so XML validation and other diagnostics appear before Alloy's generic compiler failure. It then prints a final hint to run `purgetss` from the project root and rethrows the error.
+
+Current `init` runs update an older active or disabled hook without changing its enabled state. Invoking `watch` normally enables a disabled hook.
 
 ### 2. `purgetss` Folder
 

package/skills/purgetss/references/multi-density-images.md

@@ -189,25 +189,55 @@ This is a hint, **not an error**. The legacy 4×-from-viewBox behavior still run
 On the first run, `purgetss images` injects an `images:` block into your existing `purgetss/config.cjs` (between `brand:` and `theme:`) with these defaults:
 
 ```javascript
+// Sources in purgetss/images/ are 4x masters: a 1024px file yields
+// 256 (mdpi/@1x), 384 (hdpi), 512 (xhdpi/@2x), 768 (xxhdpi/@3x), 1024 (xxxhdpi).
+// There is no width to configure here — the source's own pixels decide.
+// SVGs have no natural pixels; pin theirs in files: [] below.
 images: {
-  autoSync: true,          // false = SVG pipeline computes dims but doesn't write to images.files
-  quality: 85,             // JPEG/WebP/AVIF quality (0-100)
+  quality: 85,             // webp/jpeg/avif/tiff quality (0-100); PNG and GIF ignore it
   format: null,            // null = keep original; 'webp' | 'jpeg' | 'png' to convert every image
+  autoSync: true,          // false = SVG pipeline computes dims but doesn't write to images.files
   confirmOverwrites: true, // prompt before overwriting files (set false to skip)
   files: []                // per-file overrides: [{ filename: 'images/<sub>/<name>.<ext>', width, height? }]
 }
 ```
 
+Since v7.17.0 the four comment lines above the section ship with the block itself, and the same text seeds through `init`. Reproduce the key order above when writing a config by hand — it is the order both generated copies use.
+
 | Key | Default | Purpose |
 | --- | --- | --- |
-| `autoSync` | `true` | When `false`, the SVG pipeline still computes dimensions and generates PNGs but never writes back to `images.files`. See [SVG-aware compile-time pipeline](./svg-pipeline.md). |
-| `quality` | `85` | Quality for lossy formats (JPEG, WebP, AVIF). Range `0–100`. |
+| `quality` | `85` | Range `0–100`. Reaches `webp`, `jpeg`, `avif` and `tiff` only. PNG is written with `compressionLevel: 9` and GIF takes no quality parameter, so the value never applies to either. |
 | `format` | `null` | `null` keeps each source's original format. Set `'webp'`, `'jpeg'`, or `'png'` to convert every output. |
+| `autoSync` | `true` | When `false`, the SVG pipeline still computes dimensions and generates PNGs but never writes back to `images.files`. See [SVG-aware compile-time pipeline](./svg-pipeline.md). |
 | `confirmOverwrites` | `true` | When `false`, the `[y/N/a]` prompt is skipped. |
 | `files` | `[]` | Per-file dimension overrides. See [Per-file overrides](#per-file-overrides-with-imagesfiles). |
 
 Change whatever you want to override globally; CLI flags still win for one-off runs. `autoSync` and `files` arrived in v7.11.0 to support the [SVG-aware compile-time pipeline](./svg-pipeline.md).
 
+### Unknown keys are an error (v7.17.0)
+
+Those five keys are the entire section. Since v7.17.0 anything else aborts the run before a single file is written, the same validation `brand:` has had since v7.13.0:
+
+```text
+> purgetss images
+Error running images: Unknown key(s) in the images: section of purgetss/config.cjs:
+  • images.qualty
+  • images.files[0].widht
+
+  Top-level keys: quality, format, autoSync, confirmOverwrites, files
+  Inside files[]: filename, width, height
+
+  Check the spelling. No images were generated.
+```
+
+A `qualty: 95` that gets ignored is indistinguishable from the default, so before v7.17.0 the typo produced the wrong output silently. The check runs at both levels and reports every problem in one pass:
+
+- **Top level** — only `quality`, `format`, `autoSync`, `confirmOverwrites`, `files`.
+- **Inside each `files[]` entry** — only `filename`, `width`, `height`. `filename` is **required** and must be a string; an entry without one matches no file and used to be skipped in the same silence.
+- `files` itself must be an array, and each entry an object.
+
+Do not suggest `width`, `opacity`, `padding` or `output` as `images:` keys. They are CLI flags and were never part of the section — the validator now names them as errors instead of ignoring them. When one file needs a fixed width, pin it in `files`; the other three describe a single run.
+
 ## Per-file overrides with `images.files`
 
 `images.files` (v7.11.0) is an array of per-file dimension pins. It does **not** filter which images get processed — `purgetss images` always walks every supported file under `purgetss/images/`. Entries in `files` only override the source and derived sizing for files whose `filename` matches.
@@ -484,7 +514,7 @@ If you only tweaked CSS classes (no image changes), you don't need to re-run `pu
 | Flag | Purpose |
 | --- | --- |
 | `--format <ext>` | Convert all outputs to: `webp`, `jpeg`, `png`, `avif`, `gif`, `tiff`. Default: keep source format. |
-| `--quality <n>` | Quality `0–100` for lossy formats. Default `85`. |
+| `--quality <n>` | Quality `0–100` for `webp`, `jpeg`, `avif` and `tiff`. PNG and GIF ignore it. Default `85`. |
 | `--width <n>` | (v7.8.0) Pin `mdpi` / `@1x` output width to `n` pixels; `[1, 8192]`. Other densities derive from this base (×1.5 / ×2 / ×3 / ×4). Most useful for SVG sources with non-standard viewBoxes. CLI-only — no `config.cjs` equivalent because width is per-asset. |
 | `--opacity <n>` | (v7.10.0) Multiply the alpha channel of every generated density by `n/100`. Range `[0, 100]`. Combine with `--format jpeg` and the alpha is flattened on white instead of producing a transparent JPEG. CLI-only. |
 | `--padding <n>` | (v7.10.0) Shrink the rendered image inside each density canvas by `n%` symmetric borders. Range `[0, 40]`. CLI-only. |

package/skills/purgetss/references/purgetss-ui-classic.md

@@ -0,0 +1,341 @@
+# `purgetss.ui` in Titanium Classic
+
+Titanium Classic uses the same generated `purgetss.ui` runtime as Alloy, but it does not compile Alloy XML, TSS, utility classes, controllers, or `$.*` references. Configure the runtime with JavaScript objects containing native Titanium properties.
+
+<!-- TOC-START -->
+## Contents
+
+- [Install and load](#install-and-load)
+- [Public exports](#public-exports)
+- [Quick start](#quick-start)
+- [Animation method contract](#animation-method-contract)
+- [Native animation configuration](#native-animation-configuration)
+- [States and direct children](#states-and-direct-children)
+- [Position helpers](#position-helpers)
+- [Drag and collision configuration](#drag-and-collision-configuration)
+- [Drag lifecycle and cleanup](#drag-lifecycle-and-cleanup)
+- [Layout transitions](#layout-transitions)
+- [Appearance in Classic](#appearance-in-classic)
+- [Runtime utilities](#runtime-utilities)
+- [Related references](#related-references)
+
+<!-- TOC-END -->
+
+## Install and load
+
+Run this from the Classic project root:
+
+```bash
+purgetss module
+```
+
+The command creates `Resources/lib/purgetss.ui.js`. Load it from a file such as `Resources/app.js`:
+
+```javascript
+const {
+  createAnimation,
+  Appearance,
+  deviceInfo,
+  saveComponent
+} = require('lib/purgetss.ui')
+```
+
+Use `createAnimation(args)` for ordinary Classic code. It returns a zero-size, touch-disabled `Ti.UI.View` decorated with animation methods. Treat this view as a behavior object; do not add it to the window.
+
+## Public exports
+
+| Export | Type and return | Contract |
+| --- | --- | --- |
+| `AnimationProperties` | Constructor returning the decorated animation view | Public, but less clear than the factory in Classic |
+| `createAnimation(args)` | Factory returning the decorated animation view | Preferred Classic entry point |
+| `Appearance` | Singleton object | `init()`, `set()`, `get()`, `toggle()` |
+| `deviceInfo()` | Function returning `undefined` | Logs platform and display information |
+| `saveComponent({ source, directory? })` | Function returning `undefined` | Writes a PNG and invokes the photo-gallery API |
+
+## Quick start
+
+```javascript
+const { createAnimation, Appearance } = require('lib/purgetss.ui')
+
+Appearance.init()
+
+const window = Ti.UI.createWindow({ backgroundColor: 'surfaceColor' })
+const card = Ti.UI.createView({
+  width: 220,
+  height: 120,
+  backgroundColor: 'accentColor',
+  opacity: 0,
+  transform: Ti.UI.createMatrix2D().scale(0.92)
+})
+const motion = createAnimation({
+  duration: 220,
+  curve: Ti.UI.ANIMATION_CURVE_EASE_OUT,
+  animationProperties: {
+    open: { opacity: 1, scale: 1 },
+    close: { opacity: 0, scale: 0.92 }
+  }
+})
+
+function onCardClick() { motion.play(card) }
+function onWindowOpen() { motion.open(card) }
+function disposeWindow() {
+  card.removeEventListener('click', onCardClick)
+  window.removeEventListener('open', onWindowOpen)
+  window.removeEventListener('close', disposeWindow)
+}
+
+card.addEventListener('click', onCardClick)
+window.add(card)
+window.addEventListener('open', onWindowOpen)
+window.addEventListener('close', disposeWindow)
+window.open()
+```
+
+`surfaceColor` and `accentColor` are names from `Resources/semantic.colors.json`; see [appearance-module.md#titanium-classic](./appearance-module.md#titanium-classic).
+
+## Animation method contract
+
+| Method | Signature | Return and callback |
+| --- | --- | --- |
+| `play` | `play(viewOrViews, callback?)` | `undefined`; callback once per view after its base animation completes |
+| `toggle` | `toggle(viewOrViews, callback?)` | Exact alias of `play` |
+| `apply` | `apply(viewOrViews, callback?)` | `undefined`; synchronous callback once per view |
+| `open` | `open(viewOrViews, callback?)` | `undefined`; forces open state, callback once per view |
+| `close` | `close(viewOrViews, callback?)` | `undefined`; forces close state, callback once per view |
+| `draggable` | `draggable(viewOrViews)` | `undefined` |
+| `undraggable` | `undraggable(viewOrViews)` | `undefined` |
+| `detectCollisions` | `detectCollisions(views, dragCallback?, dropCallback?)` | `undefined` |
+| `sequence` | `sequence(viewOrViews, callback?)` | `undefined`; callback once after the final view |
+| `swap` | `swap(view1, view2)` | `undefined` |
+| `pulse` | `pulse(view, count = 1)` | `undefined` |
+| `shake` | `shake(view, intensity = 10)` | `undefined` |
+| `snapTo` | `snapTo(view, targets)` | Selected target, `null` if none qualifies, or `undefined` for a missing source |
+| `reorder` | `reorder(views, newOrder)` | `undefined` |
+| `transition` | `transition(viewOrViews, layouts)` | `undefined` |
+
+`play`, `toggle`, `apply`, `open`, and `close` accept one view or an array. The array callback runs once per view with:
+
+- `type`: native completion type, or `'applied'` for `apply`.
+- `bubbles` and `cancelBubble`: selected native primitives.
+- `action`: `'play'` or `'apply'`.
+- `state`: `'open'` or `'close'`.
+- `id` and `targetId`.
+- `index` and `total`.
+- `getTarget()`: returns the affected view.
+
+This is a newly constructed object, not the original Titanium event. For array playback, the configured base delay accumulates for successive views. `sequence()` instead waits for each native completion and invokes its callback once after the last view. Passing an empty array to `sequence()` produces no callback.
+
+`animationProperties.complete` starts after the active `play`, `toggle`, `open`, or `close` base phase, and is applied immediately after `apply`. The public play callback does not wait for the second top-level `complete` animation.
+
+## Native animation configuration
+
+Pass native `Ti.UI.Animation` values directly:
+
+```javascript
+const { createAnimation } = require('lib/purgetss.ui')
+
+const motion = createAnimation({
+  id: 'cardMotion',
+  duration: 240,
+  delay: 40,
+  curve: Ti.UI.ANIMATION_CURVE_EASE_IN_OUT,
+  repeat: 1,
+  autoreverse: false,
+  opacity: 0.8,
+  backgroundColor: '#2563eb',
+  scale: 1.05,
+  rotate: 4
+})
+```
+
+The constructor removes `id` from the native animation object. It converts top-level `scale`, `rotate`, and `anchorPoint` into one `Ti.UI.Matrix2D`; it performs the same conversion separately for `animationProperties.open` and `.close`. Helpers such as `pulse`, `shake`, `swap`, `snapTo`, `reorder`, and `transition` can replace or reset that transform.
+
+Most helpers spread the base object before their method-specific assignments, so later helper fields win. There is no shared `200ms` timing fallback for position/layout helpers. Only `shake()` computes `(duration ?? 400) / 6`, rounded to the nearest millisecond; `pulse()` supplies a default scale of `1.2`. Both force `ANIMATION_CURVE_EASE_IN_OUT`.
+
+Titanium exposes `anchorPoint` differently across platforms. Test pivot-dependent animation on both platforms; in Classic, set the view's iOS anchor point before animation and pass an Android animation anchor point only inside a platform guard.
+
+## States and direct children
+
+```javascript
+const panelMotion = createAnimation({
+  duration: 220,
+  animationProperties: {
+    open: { opacity: 1, scale: 1 },
+    close: { opacity: 0, scale: 0.94 },
+    complete: { borderColor: '#22c55e' },
+    children: { duration: 160 }
+  }
+})
+
+titleLabel.animationProperties = {
+  child: { delay: 40 },
+  open: { opacity: 1, top: 16 },
+  close: { opacity: 0, top: 24 },
+  complete: { color: '#22c55e' }
+}
+
+panelMotion.open(panel)
+```
+
+For a direct child, merge precedence is:
+
+1. Parent `animationProperties.children`.
+2. Child `animationProperties.child`.
+3. Child's active `open`, `close`, or `complete` object.
+
+Later values win. Nested descendants are not traversed automatically.
+
+## Position helpers
+
+- `swap()` exchanges two rendered positions, temporarily promotes both views, persists `top`/`left`, and updates private drag origins. It restores stacking from the current draggable registry order, not arbitrary original z-index values.
+- `snapTo()` chooses the nearest target by center distance and returns it immediately. Views must be laid out because it reads `rect`.
+- `reorder()` maps each view to the captured position at `newOrder[index]`. A length mismatch returns without changes.
+- `pulse()` forces autoreverse, the supplied repeat count, and ease-in-out, then resets the transform.
+- `shake()` starts at `-intensity`, animates to `+intensity` through six short phases, and resets the transform.
+
+These methods do not expose completion callbacks. Configure duration, delay, and curve on the object passed to `createAnimation()`.
+
+## Drag and collision configuration
+
+```javascript
+const dragMotion = createAnimation({
+  duration: 160,
+  bounds: { top: 12, right: 12, bottom: 12, left: 12 },
+  draggingType: 'animate',
+  draggable: {
+    drag: { opacity: 0.7, scale: 1.04 },
+    drop: { opacity: 1, scale: 1 }
+  },
+  animationProperties: {
+    keepZIndex: true,
+    snap: { back: true, center: true }
+  }
+})
+
+piece.bounds = { bottom: 40 }
+piece.constraint = 'horizontal'
+piece.draggingType = 'apply'
+piece.draggable = {
+  drag: { opacity: 0.5 },
+  drop: { opacity: 1 }
+}
+
+dragMotion.draggable(piece)
+dragMotion.detectCollisions([piece, target], (source, hovered) => {
+  target.borderColor = hovered === target ? '#22c55e' : 'transparent'
+}, (source, droppedOn) => {
+  Ti.API.info(`${source.id} dropped on ${droppedOn.id}`)
+})
+```
+
+Runtime precedence and behavior:
+
+- Global bounds are the base; `view.bounds` overrides individual edges.
+- Axis restriction comes from `view.constraint`; a constructor-level constraint is not read.
+- Per-view `draggingType` overrides the constructor value.
+- Global and per-view `draggable.drag/drop` objects are merged; view fields win.
+- Every resolved drag/drop property is forwarded, including size, transform, and anchor-point fields.
+- `snap.center` calls `snapTo()` after a valid drop; `snap.back` returns a missed drop to its origin.
+- There is no `snap.magnet` behavior.
+- Collision detection tests the dragged view's center against registered targets. The last non-null hover target is a fallback at release.
+
+Call drag/collision setup after the views are attached and laid out. `draggable(array)` assigns each view `zIndex` from its array index before registration. `keepZIndex` only prevents later touch-start promotion; register views individually if their existing z-index values must not be overwritten.
+
+## Drag lifecycle and cleanup
+
+Register each view once. The current runtime does not deduplicate repeated `draggable()` calls: they create additional listeners and registry entries. One `undraggable()` call removes only the latest stored listener set and the first matching registry entries.
+
+`undraggable()` removes the stored `touchstart`, `touchmove`, `touchend`, and global `orientationchange` listeners and most private position/collision fields, but it leaves `_wasDragged`. `detectCollisions()` retains the last non-null callbacks on the animation object; passing `null` does not clear them.
+
+```javascript
+let dragReady = false
+
+function enableDrag() {
+  if (dragReady) return
+  dragReady = true
+  dragMotion.draggable(piece)
+  dragMotion.detectCollisions([piece, target])
+}
+
+function disposeWindow() {
+  dragMotion.undraggable([piece, target])
+  window.removeEventListener('open', enableDrag)
+  window.removeEventListener('close', disposeWindow)
+  dragReady = false
+}
+
+window.addEventListener('open', enableDrag)
+window.addEventListener('close', disposeWindow)
+```
+
+Release view, callback, and animation references after close. Application code should not depend on private underscore fields.
+
+## Layout transitions
+
+`transition(views, layouts)` accepts these layout fields:
+
+| Field | Default | Behavior |
+| --- | --- | --- |
+| `translation` | `{ x: 0, y: 0 }` | Matrix translation |
+| `rotate` | `0` | Matrix rotation in degrees |
+| `scale` | `1` | Matrix scale |
+| `zIndex` | unchanged | Assigned before animation |
+| `width`, `height` | unchanged | Optional size animation |
+| `opacity` | unchanged | Optional opacity animation |
+
+```javascript
+const layoutMotion = createAnimation({
+  duration: 220,
+  curve: Ti.UI.ANIMATION_CURVE_EASE_IN_OUT
+})
+const fan = [
+  { translation: { x: -120, y: 20 }, rotate: -15, scale: 0.8, zIndex: 1 },
+  { translation: { x: 0, y: 0 }, rotate: 0, scale: 1, zIndex: 3 },
+  { translation: { x: 120, y: 20 }, rotate: 15, scale: 0.8, zIndex: 2 }
+]
+
+layoutMotion.transition([cardA, cardB, cardC], fan)
+```
+
+A view without a matching layout fades to opacity `0`, receives `zIndex: 0`, and has touch disabled. Extra layouts are ignored. A later matching layout fades a hidden view in and reenables touch. iOS preserves the last transform while hidden; Android resets transform, translation, rotation, and scale. Completion forces `touchEnabled: true` for every matched view, so reapply `false` afterward when a view must remain non-interactive.
+
+On Mac Catalyst, use a fixed-size parent rather than `Ti.UI.FILL` for rotated layouts; a resizable parent can distort the matrix.
+
+## Appearance in Classic
+
+Put semantic colors in `Resources/semantic.colors.json`, use their names directly in native color properties, and call `Appearance.init()` before opening the first window. Classic does not need utility classes, TSS, `purgetss/config.cjs`, or Alloy runtime files. Run a full native build after adding or changing semantic keys; LiveView alone does not rebuild the native catalog.
+
+See [appearance-module.md#titanium-classic](./appearance-module.md#titanium-classic) for setup and all four method contracts.
+
+## Runtime utilities
+
+```javascript
+const { deviceInfo, saveComponent } = require('lib/purgetss.ui')
+
+deviceInfo()
+
+function savePreview() {
+  if (!Ti.Media.hasPhotoGalleryPermissions()) {
+    Ti.Media.requestPhotoGalleryPermissions(event => {
+      if (event.success) savePreview()
+    })
+    return
+  }
+
+  saveComponent({
+    source: preview,
+    directory: Ti.Filesystem.applicationDataDirectory
+  })
+}
+```
+
+`deviceInfo()` logs values and returns `undefined`. It logs `xdpi` and `ydpi` only on Android. Its tablet flag recognizes iPad only, so Android tablets are currently logged as `isTablet: false` and `isHandheld: true`.
+
+`saveComponent()` calls `source.toImage()`, derives an MD5-based `.png` filename, writes it to `directory` (default: `Ti.Filesystem.tempDirectory`), then invokes `Ti.Media.saveToPhotoGallery()`. It returns `undefined` and provides no completion or error callback. Check/request gallery permission before calling it; on iOS, declare the required photo-library add usage description.
+
+## Related references
+
+- [animation-system.md](./animation-system.md) — Alloy syntax and all animation methods.
+- [animation-advanced.md](./animation-advanced.md) — generated timing classes and runtime rules.
+- [appearance-module.md](./appearance-module.md) — Appearance workflow and API.
+- [classic-projects.md](./classic-projects.md) — commands and capabilities available to Classic projects.

package/skills/purgetss/references/version-history.md

@@ -8,6 +8,23 @@ When in doubt about whether a class, flag, or config key exists in the user's in
 
 ---
 
+## v7.17.0
+- The `images:` section rejects unknown keys instead of ignoring them, at both levels: the five top-level keys (`quality`, `format`, `autoSync`, `confirmOverwrites`, `files`) and the three inside each `files[]` entry (`filename`, `width`, `height`, with `filename` required). Nothing is generated when validation fails. Never suggest `width`, `opacity`, `padding` or `output` as config keys — they are CLI flags and now abort the run. See [multi-density-images.md](multi-density-images.md).
+- The generated `images:` block gained four comment lines explaining the 4× master convention, and the `quality` comment now names the formats it reaches: `webp`, `jpeg`, `avif`, `tiff`. PNG uses `compressionLevel: 9` and GIF takes no quality parameter, so neither is affected. Both copies changed — the one patched into an existing config and the one `init` seeds.
+- `install-dependencies` and `create --dependencies` now install only `eslint` and `@eslint/js` and copy a flat `eslint.config.mjs`. `eslint-config-axway` and `eslint-plugin-alloy` are gone: the old `.eslintrc.js` could not run under ESLint 9. See [cli-commands.md](cli-commands.md#install-dependencies-command).
+
+## v7.16.2
+- `build-fonts --module` now exports every processed TTF/OTF PostScript name through `families`, including text-only collections; icon CSS additionally populates `icons`. Filename-derived keys such as `poppinsSemiBold` are supported. See [custom-fonts.md](custom-fonts.md).
+- In clean Classic projects, saved `shades` palettes and `color-module` no longer scaffold empty brand, font, or image source folders. `shades` still refreshes an existing generated color module. See [classic-projects.md](classic-projects.md).
+
+## v7.16.1
+- Alloy auto-purge hooks now expose PurgeTSS output before Alloy's generic failure, print a command-line diagnostic hint, and migrate older active or disabled hooks without losing their state. See [installation-setup.md](installation-setup.md).
+
+## v7.16.0
+- `brand.artworkCornerRadius` and optional `brand.splashCornerRadius` add shared rounding for non-icon artwork; the iOS/Android splash, Feature Graphic, and LaunchLogo pieces also accept `cornerRadius`. Values are 0–50, and unsupported pieces reject the key before writing. Platform-masked and store icon outputs remain unrounded. See [app-branding.md](app-branding.md).
+- Six CLI radius flags provide shared, splash-only, and per-piece one-run overrides. `--appicon-padding` completes the existing `brand.appicon.padding` contract, whose canonical default is `10%`.
+- Branding summaries and `--dry-run` now report effective padding and corner radius for rounded pieces.
+
 ## v7.15.0
 - Standalone `images`, `semantic`, `shades`, `color-module`, `module`, `icon-library`, and `build-fonts` now support Classic without installing the Alloy hook or utility-class lifecycle. Outputs route to native `Resources/` paths where appropriate. See [classic-projects.md](classic-projects.md).
 - `images` follows `<deployment-targets>` from `tiapp.xml` by default; explicit `--android` / `--ios` override that selection.