@maccesar/titools 4.17.1 → 4.19.0

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

@@ -1,6 +1,6 @@
 # Icon Font Libraries
 
-PurgeTSS ships with four official icon font families, each preconfigured with the TSS classes and `fontFamily` mappings you need to drop icons into Buttons, Labels, and TextFields.
+PurgeTSS ships with four official icon font families. Alloy projects can use their preconfigured TSS classes; Classic projects can install the same fonts and use `fontFamily` plus Unicode directly or through the optional CommonJS modules.
 
 For user-defined fonts (Google Fonts, brand typefaces, community icon libraries like map-icons or microns), see [Custom Fonts](./custom-fonts.md) — those use `build-fonts`, not `icon-library`.
 
@@ -43,7 +43,7 @@ The complete class definitions live in the PurgeTSS `dist/` folder:
 
 ## Installing the icon fonts
 
-Run `icon-library` to copy the `.ttf` files into `./app/assets/fonts/`. That is the only step you need. Once the fonts are in place, the icon classes from the table above work out of the box.
+Run `icon-library` to copy the font files to `app/assets/fonts/` (Alloy) or `Resources/fonts/` (Classic). Alloy can then use the icon classes from the table; Classic does not run class resolution.
 
 ```bash
 # All four families
@@ -56,14 +56,14 @@ $ purgetss il -v=fa,mi,ms,f7
 > ℹ️ **INFO — You do not need the `.tss` files in `./purgetss/styles/`**
 > PurgeTSS already knows every official icon class and resolves them at compile time from its own bundled `dist/` files. You do not need `fontawesome.tss`, `materialsymbols.tss`, `materialicons.tss`, or `framework7icons.tss` inside `./purgetss/styles/` for `class="fas fa-home"` (or any other icon class) to work in your XML and controllers. Install the `.ttf` files with `icon-library` and the classes are ready.
 >
-> The resolved classes are written to the generated `app/styles/app.tss`, not to `purgetss/styles/utilities.tss`. If you go looking for a class like `.ms-home`, check `app.tss`.
+> The resolved Alloy classes are written to generated `app/styles/app.tss`, not `purgetss/styles/utilities.tss`. Classic receives only native fonts and any requested JavaScript module.
 
 ### Optional flags
 
 Two optional flags adjust what `icon-library` copies into your project:
 
-- `-s, --styles`: copies the official `.tss` source files into `./purgetss/styles/` for reference only. Useful if you want to grep the full class list, see how a class is defined, or override a specific class in your own project.
-- `-m, --module`: copies the matching CommonJS module into `./app/lib/`, which exposes each icon's Unicode string to JavaScript. Handy when you set `label.text` from a controller and prefer a friendly name like `icons.fa.home` over a raw ``.
+- `-s, --styles`: Alloy only. Copies the official `.tss` sources into `purgetss/styles/` for reference. Classic skips this output.
+- `-m, --module`: copies the matching CommonJS module into `app/lib/` (Alloy) or `Resources/lib/` (Classic), exposing Unicode strings and stable font-family aliases.
 
 ```bash
 # Add either flag when you want them
@@ -81,7 +81,34 @@ $ purgetss il -m -s
 - `ms`, `materialsymbol` = Material Symbols
 - `f7`, `framework7` = Framework7 Icons
 
-## Using icons in XML
+### CommonJS modules in Classic
+
+Each module exposes its existing icon lookup API plus a `families` object with `families.default`. Direct aliases are also available:
+
+| Module | Direct aliases |
+| --- | --- |
+| `fontawesome` | `solid`, `regular`, `brands` |
+| `materialicons` | `regular`, `outlined`, `round`, `sharp`, `twoTone` |
+| `materialsymbols` | `outlined`, `rounded`, `sharp` |
+| `framework7icons` | `fontFamily` |
+
+```javascript
+const fontAwesome = require('lib/fontawesome')
+
+const home = Ti.UI.createLabel({
+  text: fontAwesome.icons.home,
+  font: {
+    fontFamily: fontAwesome.solid,
+    fontSize: 24
+  }
+})
+```
+
+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
 
 The variant class sets the `fontFamily`. The icon class sets the glyph (`text` / `title`). Apply both together:
 

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

@@ -12,6 +12,12 @@ Install PurgeTSS globally on your machine using [NPM](https://www.npmjs.com/).
 > Node.js 20+ required.
 > PurgeTSS requires Node 20.0.0 or higher.
 
+## Alloy vs. Classic Setup
+
+The root `purgetss` command, `init`, `create`, `install-dependencies`, `build`, and `watch` belong to the Alloy utility-class lifecycle described below. Do not run them to “set up PurgeTSS” in a Classic project.
+
+Classic projects can run compatible standalone commands directly: `brand`, `images`, `semantic`, `shades`, `color-module`, `module`, `icon-library`, and `build-fonts`. Their native outputs go under `Resources/`, and the application does not need an `alloy.jmk` hook or PurgeTSS at compile/runtime. See [Classic Project Support](./classic-projects.md).
+
 ## XML Validation
 
 Before purging, PurgeTSS pre-checks every XML file in your project. One case worth calling out: double dashes (`--`) are not allowed inside XML comments. That restriction comes from the XML spec itself, not from PurgeTSS, but many people only run into it once a tool actually parses the file.
@@ -44,7 +50,7 @@ Pick whichever of these reads best:
 
 Any of those approaches keeps the comment readable and produces a document that every XML parser will accept.
 
-## Run PurgeTSS the First Time
+## Run PurgeTSS the First Time (Alloy Only)
 
 > **INFO**
 > Run `purgetss` once in your project to generate the required files and folders.
@@ -55,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

@@ -1,6 +1,6 @@
 # Multi-Density Images
 
-The `purgetss images` command (shipped in PurgeTSS v7.6.0) generates every Titanium density variant of your UI images — buttons, illustrations, screen graphics, inline icons, logos — from a single high-resolution source per image. Alloy and Classic layouts are auto-detected.
+The `purgetss images` command generates every Titanium density variant of your UI images from one high-resolution source. Alloy and Classic layouts are auto-detected. Since v7.15.0, a normal run follows the enabled platforms in `tiapp.xml`; `--android` and `--ios` are explicit overrides.
 
 - **Android**: `res-mdpi`, `res-hdpi`, `res-xhdpi`, `res-xxhdpi`, `res-xxxhdpi` (5 densities)
 - **iPhone**: `@1x`, `@2x`, `@3x` (3 scales via filename suffix)
@@ -10,7 +10,7 @@ For the terse flag reference, see the [`images` command reference](./cli-command
 > **INFO**
 >
 > The `images` command at a glance
-> One source per image in `purgetss/images/`, run `purgetss images`, and every density lands in the right place under `app/assets/android/images/res-*/` and `app/assets/iphone/images/`. Works on both Alloy and Classic projects.
+> One source per image in `purgetss/images/`, run `purgetss images`, and every density lands under `app/assets/` (Alloy) or `Resources/` (Classic).
 
 <!-- TOC-START -->
 ## Contents
@@ -80,11 +80,11 @@ app/assets/
         └── primary@3x.svg
 ```
 
-Classic projects output to `assets/android/images/res-*/` and `assets/iphone/images/` under the project root instead of under `app/assets/` — the command auto-detects the layout.
+Classic projects output to `Resources/android/images/res-*/` and `Resources/iphone/images/` — the command auto-detects the layout.
 
 ## The `purgetss/images/` convention
 
-`init` creates `purgetss/images/` (alongside `fonts/` and `brand/`), so the folder is already there the first time you look for it, even before you've dropped any sources.
+Alloy `init` creates `purgetss/images/` alongside `fonts/` and `brand/`. In standalone Classic, running `purgetss images` without a positional source establishes the convention folder. Passing an existing external source does not create an empty `purgetss/images/` folder or config file.
 
 ```text
 purgetss/images/
@@ -99,7 +99,7 @@ purgetss/images/
 
 Supported input formats: `.svg`, `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`.
 
-**Subdirectories are preserved in the output.** A file at `purgetss/images/buttons/primary.png` ends up at `app/assets/android/images/res-*/buttons/primary.png` and `app/assets/iphone/images/buttons/primary.png`. Organize however makes sense for your project.
+**Subdirectories are preserved in the output.** A file at `purgetss/images/buttons/primary.png` ends up under the matching `app/assets/` or `Resources/` platform roots. Organize however makes sense for your project.
 
 > **INFO**
 >
@@ -264,7 +264,7 @@ Raster entries you add by hand survive subsequent runs untouched. For SVGs detec
 
 ```text
 <project>/
-└── assets/
+└── Resources/
     ├── android/images/res-*/
     └── iphone/images/
 ```
@@ -329,11 +329,11 @@ purgetss images ./docs/screenshots/home-hero.png
 purgetss images /Users/cesar/Design/banner.svg
 ```
 
-When the source is outside `purgetss/images/`, subdirectory preservation uses the directory of the source file as the root instead.
+When the source is outside `purgetss/images/`, subdirectory preservation uses the directory of the source file as the root instead. Processing that external source in Classic does not bootstrap unrelated PurgeTSS folders or config.
 
 ## Platform filter
 
-By default, every run generates both Android densities and iPhone scales. Scope to one platform for targeted runs:
+By default, the command follows `<deployment-targets>` in `tiapp.xml`. Pass a platform flag to override that selection for a targeted run:
 
 ```bash
 purgetss images --android                # Android only (skip iPhone)
@@ -345,7 +345,7 @@ Useful when:
 - You're iterating on an iOS-only screen and don't need to regenerate Android assets every time.
 - You want to tune JPEG quality differently for the two platforms (run the command twice with different flags).
 
-The two flags are mutually exclusive. Pass neither to get both.
+The two flags are mutually exclusive. Passing neither means “use the project's enabled targets,” not “always generate both.”
 
 ## Format conversion
 
@@ -462,7 +462,7 @@ If you only tweaked CSS classes (no image changes), you don't need to re-run `pu
 
 ## Cleaning up
 
-`purgetss images` never deletes files. It only creates them. If you remove an image from `purgetss/images/`, the previously-generated copies in `app/assets/android/images/res-*/` and `app/assets/iphone/images/` stay in place. Remove them manually (or via git) when you clean up.
+`purgetss images` never deletes files. It only creates them. If you remove a source, generated copies under `app/assets/` (Alloy) or `Resources/` (Classic) stay in place. Remove them manually or with git when you clean up.
 
 ## Full flag reference
 

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/semantic-colors.md

@@ -8,7 +8,7 @@ For the mode-switching runtime that drives all of this (`Appearance.init()`, `Ap
 
 > **INFO**
 >
-> Semantic color resolution is a **Titanium** feature, not PurgeTSS magic. Titanium natively reads `semantic.colors.json` (at `app/assets/` on Alloy, `Resources/` on Classic) and resolves any color-accepting property whose value matches a key in that file. PurgeTSS only generates the utility classes that point *at* those keys — the switching behavior is 100% native.
+> Semantic color resolution is a **Titanium** feature, not PurgeTSS magic. Titanium natively reads `semantic.colors.json` (at `app/assets/` on Alloy, `Resources/` on Classic) and resolves any color-accepting property whose value matches a key in that file. In Alloy, PurgeTSS also generates utility mappings that point at those keys; Classic uses the keys directly. The switching behavior is native in both layouts.
 
 <!-- TOC-START -->
 ## Contents
@@ -17,7 +17,7 @@ For the mode-switching runtime that drives all of this (`Appearance.init()`, `Ap
 - [Registering in `config.cjs`](#registering-in-configcjs)
 - [Numeric 11-step tonal-inversion palette](#numeric-11-step-tonal-inversion-palette)
 - [The `semantic` CLI command](#the-semantic-cli-command)
-- [Using semantic classes in views](#using-semantic-classes-in-views)
+- [Using semantic classes in Alloy views](#using-semantic-classes-in-alloy-views)
 - [Using semantic colors in controllers](#using-semantic-colors-in-controllers)
 - [Recommended starter palette](#recommended-starter-palette)
 - [Related](#related)
@@ -235,13 +235,15 @@ One base hex plus a family name produces 11 JSON entries with mirror inversion,
 purgetss semantic '#15803d' amazon
 ```
 
-This:
+In Alloy, this:
 
 1. Generates `amazon50` through `amazon950` using the same algorithm as the `shades` command.
-2. Writes `semantic.colors.json` at the project's canonical location (`app/assets/` on Alloy, `Resources/` on Classic) with mirror-by-index values — 50 ↔ 950, 100 ↔ 900, …, 500 as the identical anchor.
+2. Writes `semantic.colors.json` under `app/assets/` with mirror-by-index values — 50 ↔ 950, 100 ↔ 900, …, 500 as the identical anchor.
 3. Writes the `{ 50: 'amazon50', 100: 'amazon100', ... }` mapping into `config.cjs`.
 4. Strips any prior keys for the `amazon` family before writing — re-runs cleanly replace, never duplicate.
 
+In Classic, the same command writes only the native `Resources/semantic.colors.json` entries. It does not create `purgetss/`, `config.cjs`, utility mappings, TSS, `app/`, or an Alloy hook. Use keys such as `amazon50` directly in Titanium color properties.
+
 Useful flags:
 
 - `--log` (`-l`) — preview the JSON on the console without writing anything.
@@ -270,7 +272,7 @@ purgetss semantic --single '#000000' overlayColor       --alpha 50
 
 The name is preserved verbatim as the JSON key (camelCase is respected). When `--dark` is omitted, it defaults to the light hex — useful for overlays where alpha is the only variation between modes.
 
-Single mode writes **both files** in one shot. The class name is auto-derived from the semantic key by stripping the conventional `Color` suffix and kebab-casing the rest, so `surfaceHighColor` becomes the `surface-high` class:
+In Alloy, single mode writes **both files** in one shot. The class name is auto-derived from the semantic key by stripping the conventional `Color` suffix and kebab-casing the rest, so `surfaceHighColor` becomes the `surface-high` class. In Classic, it writes only the native JSON entry and code uses the semantic key directly:
 
 `./purgetss/config.cjs` (auto-generated)
 ```js
@@ -301,7 +303,7 @@ After the batch above you can use `bg-surface`, `bg-surface-high`, `text-text`,
 
 Alpha follows the Titanium spec exactly: range `0.0-100.0`, stored as a **string**, wrapped per-mode as `{ color, alpha }`. Without `--alpha`, values stay as bare hex strings. Out-of-range values are rejected before any file is written.
 
-## Using semantic classes in views
+## Using semantic classes in Alloy views
 
 Once the JSON and the `config.cjs` mapping are in place, you use the semantic classes like any other PurgeTSS utility:
 
@@ -315,6 +317,14 @@ Once the JSON and the `config.cjs` mapping are in place, you use the semantic cl
 </Window>
 ```
 
+Classic has no utility mapping. Use the native semantic key directly:
+
+```javascript
+const window = Ti.UI.createWindow({
+  backgroundColor: 'surfaceColor'
+})
+```
+
 When the appearance changes — whether from `Appearance.set(...)` or a system-level toggle — Titanium resolves each semantic color name to its `light` or `dark` value automatically. No event listeners, no manual repaint.
 
 ### Opacity modifier auto-derivation
@@ -440,5 +450,5 @@ Start with these 6-7 colors and add more only when the design requires it. Fewer
 ## Community-Discovered Patterns
 
 - **The `[object Object]` crash is always a missing `DEFAULT`.** Any time a view renders with a mysterious fallback color and the class was something like `bg-surface`, check `config.cjs` first: if `surface` is a nested object without a `DEFAULT` key, PurgeTSS serializes the whole object and emits `[object Object]` as the color value. The fix is either to add `DEFAULT: 'surfaceColor'` inside the nested object or flatten the structure.
-- **Semantic resolution is Titanium-native, not PurgeTSS.** This matters when debugging: if a semantic name doesn't resolve, the problem is usually the `semantic.colors.json` file (wrong filename, wrong key, malformed JSON, or file in the wrong location — Alloy expects `app/assets/`, Classic expects `Resources/`), not PurgeTSS. PurgeTSS's job ends at generating the class that points at the name.
+- **Semantic resolution is Titanium-native, not PurgeTSS.** This matters when debugging: if a semantic name doesn't resolve, the problem is usually the `semantic.colors.json` file (wrong filename, wrong key, malformed JSON, or wrong location — Alloy expects `app/assets/`, Classic expects `Resources/`). PurgeTSS generates the file in both layouts and an additional utility mapping only in Alloy.
 - **Re-running `purgetss semantic` on the same family is safe.** The CLI strips prior keys for that family from both the JSON and `config.cjs` before writing, so switching between palette and single forms — or changing the base hex — does not leave orphans. Other palettes and manually-defined entries are untouched.

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

@@ -8,6 +8,34 @@ When in doubt about whether a class, flag, or config key exists in the user's in
 
 ---
 
+## 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.
+- Classic `semantic` writes only `Resources/semantic.colors.json`; external Classic `images` runs no longer create unrelated empty `purgetss/` or config artifacts.
+- Official icon-font CommonJS modules expose stable `families.default` plus variant aliases. Existing icon lookup APIs remain intact. See [icon-fonts.md](icon-fonts.md).
+
+## v7.14.0
+- `brand` became self-contained in standalone Classic projects: it creates the canonical config when missing and adopts a positional logo into `purgetss/brand/logo.{png,svg}` after confirmation when no canonical source exists.
+- Normal `brand` runs follow `tiapp.xml` deployment targets; explicit `--only` remains an intentional override.
+- Classic Android now receives the 11 `Resources/android/images/res-*` splash variants Titanium consumes, even when `ti create` did not seed the directories.
+- Square iOS/store artwork defaults to full-bleed `0%` padding. Android adaptive (`18%`), legacy (`10%`), and splash (`26%`) defaults remain platform-specific.
+- Fixes align `DefaultIcon.png` and `DefaultIcon-ios.png` with `brand.icon.padding` and make the documented legacy padding the actual per-side inset.
+
+## v7.13.2
+- `brand --help` padding defaults now come from the same piece table as the pipeline. The help output correctly reports adaptive `18%` and splash `26%`; do not preserve the older “stale help strings” warning.
+
 ## v7.13.1
 - Four vulnerable transitive dependencies patched (`postcss`, `nanoid`, `brace-expansion`, `uuid`). Lockfile only; no API or class changes.