@maccesar/titools 4.18.0 → 4.20.0

package/skills/purgetss/references/app-branding.md

@@ -30,6 +30,7 @@ For the terse flag reference, see the [`brand` command reference](./cli-commands
 - [iOS 18+ Dark and Tinted variants](#ios-18-dark-and-tinted-variants)
 - [Brand color](#brand-color)
 - [Padding guidance](#padding-guidance)
+- [Rounded non-icon artwork](#rounded-non-icon-artwork)
 - [Cleanup legacy branding artifacts](#cleanup-legacy-branding-artifacts)
 - [Troubleshooting](#troubleshooting)
 - [Flag reference](#flag-reference)
@@ -143,12 +144,14 @@ On the first run, `purgetss brand` adds a `brand:` block to your existing `purge
 
 ```javascript
 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
@@ -158,7 +161,7 @@ brand: {
   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.
@@ -170,6 +173,8 @@ brand: {
 
 Change only what you want to keep as a project default. CLI flags still win for one-off runs.
 
+Use flags for temporary artwork, geometry, the shared background, selection, activation, and optimization. Keep persistent choices such as `confirmOverwrites`, permanent `enabled` values, and exceptional per-piece backgrounds in `config.cjs`.
+
 ### Older configs update themselves
 
 PurgeTSS keeps `config.cjs` current the same way it renamed `config.js` to `config.cjs`: **on the file, once**. When the `brand:` block uses a shape from an earlier version, the next run rewrites it to the per-piece structure and carries over everything that had been customized (paddings, colors, logo paths, enabled flags), then lists each value it moved:
@@ -201,11 +206,12 @@ A key `brand:` does not define stops the run before a single file is written, at
 Unknown key(s) in the brand: section of purgetss/config.cjs:
   • brand.adaptive.paddig
 
-  Top-level keys: background, confirmOverwrites, logo, monochromeLogo
+  Top-level keys: background, artworkCornerRadius, splashCornerRadius, confirmOverwrites,
+                  optimize, logo, monochromeLogo
   Piece blocks:   icon, dark, tinted, iosSplash, launchLogo, marketplace, featureGraphic,
                   adaptive, legacyIcon, appicon, androidSplash, splashIcon,
                   notificationIcon, ninePatch
-  Inside a piece: logo, padding, background, enabled
+  Inside a piece: logo, padding, cornerRadius, background, enabled
 
   Check the spelling. Nothing was written.
 ```
@@ -214,12 +220,13 @@ A typo is deliberately **not** treated as an old structure: rewriting the block
 
 ## Brand config reference
 
-Every piece accepts the same four keys, where they apply:
+Every piece accepts the same five keys, where they apply:
 
 | Key | What it does |
 | --- | --- |
 | `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` | Rounded artwork corners, only for `iosSplash`, `androidSplash`, `featureGraphic`, and `launchLogo`; integer or percentage string from `0` through `50`. |
 | `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. |
 
@@ -228,6 +235,8 @@ And these live at the top level:
 | Key | Default | Purpose |
 | --- | --- | --- |
 | `background` | `'#FFFFFF'` | The background every piece inherits unless it declares its own: the Android adaptive background layer, the `DefaultIcon-ios.png` flatten, the splash canvases, and the marketplace flatten when a background is explicitly configured. |
+| `artworkCornerRadius` | `'0%'` | Shared radius for the four supported non-icon artwork pieces. It never changes store or launcher icons. |
+| `splashCornerRadius` | — | Optional splash-only override for `iosSplash` and `androidSplash`. |
 | `confirmOverwrites` | `true` | Whether `brand` asks before overwriting project files in place. |
 | `optimize` | `false` | Quantize the generated PNGs to a palette. Lossy — see [Shrinking the generated files](#shrinking-the-generated-files). |
 | `logo` | — | Path override for the main logo. |
@@ -576,6 +585,7 @@ Padding belongs to the piece, not to the project. Each piece has its own key and
 | --- | --- | --- | --- |
 | `adaptive` | `brand.adaptive.padding` | `--android-adaptive-padding` | `18%` |
 | `legacy-icon` | `brand.legacyIcon.padding` | `--android-legacy-padding` | `10%` |
+| `appicon` | `brand.appicon.padding` | `--appicon-padding` | `10%` |
 | `icon` | `brand.icon.padding` | `--ios-padding` | `0%` |
 | `feature-graphic` | `brand.featureGraphic.padding` | `--feature-graphic-padding` | `12%` |
 | `launch-logo` | `brand.launchLogo.padding` | `--launch-logo-padding` | `12%` |
@@ -619,6 +629,19 @@ The `26%` default is calibrated against the Titanium template itself: the Alloy
 
 Before v7.13.0 none of this was configurable: `default.png` used a hardcoded box of 72% × 26% of its own canvas, and the `res-*` set a separate hardcoded 60%. Two rules for the same piece, neither adjustable.
 
+## Rounded non-icon artwork
+
+`brand.artworkCornerRadius` rounds artwork only in the 16 iPhone launch images, Android `default.png` plus its 11 qualifier variants, `MarketplaceArtworkFeature.png`, and `LaunchLogo.png`. A piece may override it with `cornerRadius`; `brand.splashCornerRadius` is an optional shared override for the two legacy splash pieces.
+
+Values are integer numbers or percentage strings from `0` through `50`, measured against the shorter side of the resized artwork. `0%` preserves the previous output byte for byte; `50%` makes square artwork circular and a wordmark capsule-shaped. Normal and `--dry-run` summaries report the effective padding and radius.
+
+Precedence is:
+
+- Feature Graphic / LaunchLogo: piece-specific flag → `--artwork-corner-radius` → piece config → `brand.artworkCornerRadius` → `0%`.
+- Legacy splashes: platform flag → `--splash-corner-radius` → `--artwork-corner-radius` → piece config → `brand.splashCornerRadius` → `brand.artworkCornerRadius` → `0%`.
+
+Store and launcher icons remain unmasked for platform processing. `cornerRadius` is rejected in `DefaultIcon*`, `iTunesConnect.png`, `MarketplaceArtwork.png`, adaptive, legacy, and app icons, Android 12+ `splash_icon.png`, notification icons, and any other unsupported piece; invalid, fractional, negative, non-numeric, or greater-than-50 values also abort before files are written.
+
 ### Adaptive icon padding
 
 Android's adaptive canvas is 108 dp. The mask leaves roughly 72 dp visible, and the **guaranteed** safe area is a 66 dp circle inscribed in it. What each padding means in those terms:
@@ -753,7 +776,7 @@ All 5 Android densities, marketplace artwork, splash canvases, and iOS variants
 
 ## Flag reference
 
-Every flag lives in the terse reference: [`brand` command](./cli-commands.md#brand-command) — project & output, `--only`, padding, optional asset types, the `--<piece>-logo` overrides, `--optimize`, appearance, legacy cleanup and diagnostics, with examples.
+Every flag lives in the terse reference: [`brand` command](./cli-commands.md#brand-command) — project & output, `--only`, padding and corner radius, optional asset types, the `--<piece>-logo` overrides, `--optimize`, appearance, legacy cleanup and diagnostics, with examples.
 
 ## Community-Discovered Patterns
 

package/skills/purgetss/references/appearance-module.md

@@ -1,6 +1,6 @@
 # Appearance Module
 
-The `Appearance` export from `purgetss.ui` (added in **v7.5.3**) handles Light / Dark / System mode switching and persists the user's choice across app restarts. It is a thin, deterministic wrapper around Titanium's native `Ti.UI.overrideUserInterfaceStyle` plus `Ti.App.Properties`, exposed as a singleton so every controller in the app reads and writes the same state.
+The `Appearance` export from `purgetss.ui` (added in **v7.5.3**) handles Light / Dark / System mode switching and persists the user's choice across app restarts. It is a thin, deterministic wrapper around Titanium's native `Ti.UI.overrideUserInterfaceStyle` plus `Ti.App.Properties`, exposed as a singleton so every Alloy controller or Classic module reads and writes the same state.
 
 This reference follows the same workflow-first / API-second split the official PurgeTSS documentation now uses:
 
@@ -18,7 +18,7 @@ For the color wiring that actually makes the UI *respond* to mode changes, see [
 The Appearance module sits between three moving parts: a JS singleton, the OS-level interface style, and the semantic colors generated by PurgeTSS. The diagram below shows how a single `Appearance.init()` call at startup wires them together, and what happens when the user later picks a mode in Settings.
 
 ```
-┌─ app/lib/appearance.js (singleton from purgetss.ui) ─────────────────┐
+┌─ Appearance singleton from purgetss.ui ──────────────────────────────┐
 │                                                                      │
 │   Appearance.init()  ────► reads 'userInterfaceStyle'                │
 │                            from Ti.App.Properties                    │
@@ -160,16 +160,67 @@ The background, text, border, and icon colors in the XML come from semantic colo
 
 > **Why named functions in Alloy controllers?** Alloy resolves `onClick="selectDark"` by looking up a top-level identifier on the controller scope. Named function declarations (`function selectDark() { ... }`) hoist and are reliably resolvable; arrow functions assigned to `const` are not hoisted and tend to bite you when an XML attribute fires before the binding has executed. The official setup guide uses named functions for this reason.
 
+## Titanium Classic
+
+Classic loads the generated runtime from `Resources/lib/purgetss.ui.js` and keeps the native color catalog at `Resources/semantic.colors.json`:
+
+```json
+{
+  "surfaceColor": { "light": "#F8FAFC", "dark": "#0F172A" },
+  "textColor": { "light": "#0F172A", "dark": "#F8FAFC" },
+  "accentColor": { "light": "#2563EB", "dark": "#60A5FA" }
+}
+```
+
+Use those semantic names directly in native Titanium color properties. Classic does not need PurgeTSS utility classes, TSS, `purgetss/config.cjs`, or any Alloy runtime file.
+
+```javascript
+const { Appearance } = require('lib/purgetss.ui')
+
+Appearance.init()
+
+const window = Ti.UI.createWindow({ backgroundColor: 'surfaceColor' })
+const title = Ti.UI.createLabel({
+  text: `Mode: ${Appearance.get()}`,
+  color: 'textColor'
+})
+const toggleButton = Ti.UI.createButton({
+  title: 'Toggle appearance',
+  color: 'surfaceColor',
+  backgroundColor: 'accentColor'
+})
+
+function toggleAppearance() {
+  Appearance.toggle()
+  title.text = `Mode: ${Appearance.get()}`
+}
+
+function disposeWindow() {
+  toggleButton.removeEventListener('click', toggleAppearance)
+  window.removeEventListener('close', disposeWindow)
+}
+
+toggleButton.addEventListener('click', toggleAppearance)
+window.add(title)
+window.add(toggleButton)
+window.addEventListener('close', disposeWindow)
+window.open()
+```
+
+Run a full native build after adding or changing semantic keys. A LiveView reload alone does not refresh Titanium's native color catalog. The `purgetss semantic` command can create the JSON for a Classic project; it writes only `Resources/semantic.colors.json`, not `config.cjs`, TSS, or utility mappings.
+
+For animation and runtime lifecycle examples in the same Classic application, see [purgetss-ui-classic.md](./purgetss-ui-classic.md).
+
 ## API reference
 
 ### Methods
 
-| Method       | Description                                                                 |
-| ------------ | --------------------------------------------------------------------------- |
-| `init()`     | Restore the saved mode from `Ti.App.Properties` and apply it via `Ti.UI.overrideUserInterfaceStyle`. Call once at app startup before opening the first window. |
-| `set(mode)`  | Apply and persist a mode. Accepts `'system'`, `'light'`, or `'dark'`. Any other value is silently ignored. |
-| `get()`      | Returns the current mode as a string: `'system'`, `'light'`, or `'dark'`.   |
-| `toggle()`   | Switch between `'light'` and `'dark'`. Skips `'system'` — if current mode is `'system'` the next call produces `'dark'`. |
+| Method | Description | Return |
+| --- | --- | --- |
+| `init()` | Restore the saved mode from `Ti.App.Properties` and apply it via `Ti.UI.overrideUserInterfaceStyle`. Call once at app startup before opening the first window. | `undefined` |
+| `set(mode)` | Apply and persist a mode. Accepts `'system'`, `'light'`, or `'dark'`. Any other value is silently ignored. | `undefined` |
+| `get()` | Read the current mode as `'system'`, `'light'`, or `'dark'`. | Mode string |
+| `toggle()` | Switch between `'light'` and `'dark'`. Skips `'system'` — if current mode is `'system'` the next call produces `'dark'`. | `undefined` |
 
 All four methods are **synchronous**. They do not fire events; if you need to react to a mode change, call your update logic right after `Appearance.set(...)`.
 
@@ -210,10 +261,13 @@ app startup
 ## Related
 
 - [semantic-colors.md](./semantic-colors.md) — defining `app/assets/semantic.colors.json` and mapping the color names in `config.cjs` so views actually respond to mode changes.
-- [cli-commands.md#semantic-command](./cli-commands.md#semantic-command) — the `purgetss semantic` command, which writes both the JSON and the `config.cjs` mapping for you.
+- [cli-commands.md#semantic-command](./cli-commands.md#semantic-command) — the `purgetss semantic` command; Alloy also receives `config.cjs` mappings, while Classic receives only the native JSON.
 - [customization-deep-dive.md](./customization-deep-dive.md) — full `config.cjs` structure, including the `theme.extend.colors` section where semantic names are registered.
+- [purgetss-ui-classic.md](./purgetss-ui-classic.md) — generated module path, Classic animation factory, method contracts, and cleanup.
 
 ## Community-Discovered Patterns
 
+These field-tested patterns are now also confirmed by the official Appearance documentation:
+
 - **Always call `Appearance.init()` before opening the first window.** Opening the window first causes a visible flicker on cold launch as the UI repaints from the system default to the saved mode. The official best-practices guide puts `Appearance.init()` on line 3 of `app/controllers/index.js`, immediately before `$.navWin.open()`, for exactly this reason.
 - **`toggle()` is not a three-state cycle.** It only alternates between `'light'` and `'dark'`. If the saved mode is `'system'`, the first `toggle()` call lands on `'dark'`. Build a cycle yourself with `get()` + `set(...)` when you need one.

package/skills/purgetss/references/class-categories.md

@@ -193,8 +193,8 @@ Complete inventory of all class prefixes organized by functional category. For n
 | `duration-*` | 22 | `duration-0`, `duration-50` to `duration-5000` |
 | `delay-*` | 22 | `delay-0`, `delay-50` to `delay-5000` |
 | `repeat-*` | ~31 | `repeat-*` variants |
-| `snap-*` (v7.4.0+) | 6 | `snap-back`, `snap-back-false`, `snap-center`, `snap-center-false`, `snap-magnet`, `snap-magnet-false` — drop behaviors for draggable views |
-| `keep-z-index` (v7.4.0+) | 2 | `keep-z-index`, `keep-z-index-false` — preserves z-order during drag when using `transition` layouts |
+| `snap-*` runtime behavior (v7.4.0+) | 4 | `snap-back`, `snap-back-false`, `snap-center`, `snap-center-false` — implemented drop behaviors. Generated inventories may still contain `snap-magnet*`, but the runtime does not consume them |
+| `keep-z-index` (v7.4.0+) | 2 | `keep-z-index`, `keep-z-index-false` — prevents touch-start promotion; it does not stop `draggable(array)` from assigning index-based z-order |
 
 ### Shadows & Elevation
 

package/skills/purgetss/references/class-index.md

@@ -196,7 +196,7 @@ The rest of this document collects conventions, prohibitions, and insights surfa
 
 ## All 364 Unique Prefixes (Alphabetical)
 
-> **NOTE**: Recent additions — v7.4.0 introduced `snap-back`, `snap-back-false`, `snap-center`, `snap-center-false`, `snap-magnet`, `snap-magnet-false`, `keep-z-index`, and `keep-z-index-false` for the Animation module drop/drag system. v7.5.3 introduced font-family classes `font-sans`, `font-serif`, `font-mono` alongside the existing weight classes.
+> **NOTE**: v7.4.0 introduced `snap-back`, `snap-back-false`, `snap-center`, `snap-center-false`, `snap-magnet`, `snap-magnet-false`, `keep-z-index`, and `keep-z-index-false`. The current runtime implements back, center, and touch-start z-index preservation but does not read `snap.magnet`; do not suggest the generated magnet classes as working behavior. v7.5.3 added `font-sans`, `font-serif`, and `font-mono`.
 
 
 ```

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

@@ -1,6 +1,6 @@
 # Classic Project Support
 
-PurgeTSS 7.15 keeps its utility-class lifecycle Alloy-only while allowing independent asset and CommonJS commands to run in Titanium Classic projects. Detect the project layout before choosing a command or output path.
+Since PurgeTSS 7.15, the utility-class lifecycle remains Alloy-only while independent asset and CommonJS commands can run in Titanium Classic projects. Detect the project layout before choosing a command or output path.
 
 Official source: <https://purgetss.com/docs/commands#alloy-and-classic-compatibility>
 
@@ -11,8 +11,8 @@ Official source: <https://purgetss.com/docs/commands#alloy-and-classic-compatibi
 | `brand` | yes | yes | Writes branding assets to Classic paths and follows enabled `tiapp.xml` deployment targets; explicit `--only` overrides that filter. |
 | `images` | yes | yes | Writes density variants under `Resources/android/images/res-*/` and `Resources/iphone/images/`; follows deployment targets unless `--android` or `--ios` is explicit. |
 | `semantic` | yes | yes | Writes only `Resources/semantic.colors.json`; it does not create `purgetss/`, `config.cjs`, TSS, `app/`, or a hook. |
-| `shades` | yes | yes | Output-only modes work anywhere. Saving creates or updates `purgetss/config.cjs` as a development-time color source. |
-| `color-module` | yes | yes | Writes `app/lib/purgetss.colors.js` or `Resources/lib/purgetss.colors.js`. |
+| `shades` | yes | yes | Output-only modes work anywhere. On a fresh Classic project, saving creates only `purgetss/config.cjs`; if the color module already exists, it is regenerated. |
+| `color-module` | yes | yes | Writes `app/lib/purgetss.colors.js` or `Resources/lib/purgetss.colors.js`; Classic creates no unrelated empty source folders. |
 | `module` | yes | yes | Writes `app/lib/purgetss.ui.js` or `Resources/lib/purgetss.ui.js`. |
 | `icon-library` | yes | yes | Copies fonts to `Resources/fonts/` and optional modules to `Resources/lib/`; `--styles` is skipped in Classic. |
 | `build-fonts` | yes | yes | Copies fonts to `Resources/fonts/` and optionally writes `Resources/lib/purgetss.fonts.js`; it does not generate TSS in Classic. |
@@ -30,12 +30,14 @@ A Classic project does not receive or need:
 - `alloy.jmk`
 - utility classes in views or controllers
 - `$.UI.create()`
-- PurgeTSS during application compilation or at runtime
+- the PurgeTSS CLI/package during application compilation or as an app dependency (generated CommonJS modules execute normally)
 
 Files generated under `Resources/` are native Titanium resources. Compile the Classic app normally with `ti build`.
 
 Do not interpret the presence of `purgetss/config.cjs` in a Classic project as permission to use utilities. Commands such as `brand`, `images`, `shades`, and `color-module` may use that file as development-time input without installing the Alloy lifecycle.
 
+Classic `shades` and `color-module` do not scaffold the empty `purgetss/brand/`, `purgetss/fonts/`, or `purgetss/images/` conventions created by Alloy initialization. On a fresh project, `shades` creates only its config; `color-module` creates that config when missing plus its module. If the module already exists, saving a palette refreshes it automatically.
+
 ## Layout and Output Routing
 
 | Artifact | Alloy | Classic |
@@ -45,9 +47,25 @@ Do not interpret the presence of `purgetss/config.cjs` in a Classic project as p
 | iPhone UI scales | `app/assets/iphone/images/` | `Resources/iphone/images/` |
 | Font files | `app/assets/fonts/` | `Resources/fonts/` |
 | Color module | `app/lib/purgetss.colors.js` | `Resources/lib/purgetss.colors.js` |
-| UI module | `app/lib/purgetss.ui.js` | `Resources/lib/purgetss.ui.js` |
+| UI module | `app/lib/purgetss.ui.js` | `Resources/lib/purgetss.ui.js` (see [`purgetss.ui` in Classic](./purgetss-ui-classic.md)) |
 | Custom-font module | `app/lib/purgetss.fonts.js` | `Resources/lib/purgetss.fonts.js` |
 
+## Loading Generated Modules in Classic
+
+Titanium resolves local CommonJS paths from `Resources/`. Omit both the `Resources/` prefix and the `.js` extension from `require()`.
+
+| Generated file | Classic `require()` path |
+| --- | --- |
+| `Resources/lib/purgetss.colors.js` | `require('lib/purgetss.colors')` |
+| `Resources/lib/purgetss.ui.js` | `require('lib/purgetss.ui')` |
+| `Resources/lib/purgetss.fonts.js` | `require('lib/purgetss.fonts')` |
+| `Resources/lib/fontawesome.js` | `require('lib/fontawesome')` |
+| `Resources/lib/materialicons.js` | `require('lib/materialicons')` |
+| `Resources/lib/materialsymbols.js` | `require('lib/materialsymbols')` |
+| `Resources/lib/framework7icons.js` | `require('lib/framework7icons')` |
+
+This follows Titanium's [CommonJS module path resolution](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_Guide/Best_Practices_and_Recommendations/CommonJS_Modules_in_Titanium.html#javascript-module-path-resolution).
+
 ## Deployment Targets
 
 `brand` and `images` read `<deployment-targets>` from `tiapp.xml` independently of whether the layout is Alloy or Classic.
@@ -94,3 +112,4 @@ When auditing a Classic project that uses PurgeTSS:
 - [Semantic Colors](./semantic-colors.md)
 - [Icon Font Libraries](./icon-fonts.md)
 - [Custom Fonts](./custom-fonts.md)
+- [`purgetss.ui` in Titanium Classic](./purgetss-ui-classic.md)

package/skills/purgetss/references/cli-commands.md

@@ -70,25 +70,32 @@ 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)
+    background: '#FFFFFF',      // inherited by every piece that doesn't set its own
+    artworkCornerRadius: '0%',  // 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)
 
     // One block per piece — see the `brand` Command section for the full list.
     icon: { padding: '0%' }, dark: { background: null }, tinted: {},
     iosSplash: { padding: '26%' }, launchLogo: { padding: '12%' },
     marketplace: {}, featureGraphic: { padding: '12%' },
     adaptive: { padding: '18%' }, legacyIcon: { padding: '10%' },
-    appicon: {}, androidSplash: { padding: '26%' },
+    appicon: { padding: '10%' }, androidSplash: { padding: '26%' },
 
     // Opt-in: inert until you edit the Android theme / FCM meta-data by hand.
     splashIcon: { enabled: false }, notificationIcon: { enabled: false },
     ninePatch: { enabled: false }
   },
+  // 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: {
-    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
-    confirmOverwrites: true  // prompt before overwriting files (set false to skip)
+    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? }]
   },
   theme: {
     extend: {}
@@ -170,7 +177,7 @@ Recommended VSCode extensions:
 
 ### Commands Executed Internally
 
-`purgetss create "Name of the Project" [--dependencies --vendor=fa,mi,ms,f7]` runs: `ti config` (reads idprefix/workspace), `ti create -t app -p all -n "Name"`, `alloy new`, `purgetss w`, `purgetss b`, optional `--vendor` (copies fonts + CommonJS module), optional `--dependencies` (installs Tailwind CSS, ESLint with Titanium plugins, and config files), then opens the project in VS Code, Sublime Text, or Finder.
+`purgetss create "Name of the Project" [--dependencies --vendor=fa,mi,ms,f7]` runs: `ti config` (reads idprefix/workspace), `ti create -t app -p all -n "Name"`, `alloy new`, `purgetss w`, `purgetss b`, optional `--vendor` (copies fonts + CommonJS module), optional `--dependencies` (installs Tailwind CSS and ESLint, and copies the config files — see [`install-dependencies`](#install-dependencies-command)), then opens the project in VS Code, Sublime Text, or Finder.
 
 ## `brand` Command
 
@@ -211,15 +218,20 @@ The 14 pieces, their config keys and what each one writes are tabulated in [app-
 | `--padding <n>` | Shortcut: sets both Android launcher paddings to the same value for one run. |
 | `--android-adaptive-padding <n>` | Adaptive icon safe-zone % (default `18`). |
 | `--android-legacy-padding <n>` | Legacy `ic_launcher.png` padding % (default `10`). |
+| `--appicon-padding <n>` | `appicon.png` padding % (default `10`). |
 | `--ios-padding <n>` | Padding % for the four square iOS/marketplace pieces — `icon`, `dark`, `tinted`, `marketplace` (default `0`, full-bleed). |
 | `--feature-graphic-padding <n>` | Vertical padding % for `MarketplaceArtworkFeature.png` (range `0-40`, default `12`). |
 | `--launch-logo-padding <n>` | Padding % for `LaunchLogo.png` (default `12`). |
 | `--splash-padding <n>` | Shortcut: sets both splash paddings to the same value for one run. |
 | `--android-splash-padding <n>` | Padding % for `default.png` and the 11 `res-*` splashes (default `26`). |
 | `--ios-splash-padding <n>` | Padding % for the 16 iPhone launch images (default `26`). |
+| `--artwork-corner-radius <n>` / `--splash-corner-radius <n>` | Shared non-icon radius, or a splash-only one-run override (range `0-50`, default `0`). |
+| `--ios-splash-corner-radius <n>` / `--android-splash-corner-radius <n>` | Per-platform legacy splash artwork radius (range `0-50`). |
+| `--feature-graphic-corner-radius <n>` / `--launch-logo-corner-radius <n>` | Per-piece Feature Graphic or LaunchLogo artwork radius (range `0-50`). |
 
 Splash padding is a share of the canvas's **shorter** side, so one number keeps the logo at the same visual weight in portrait and in landscape: the `26%` default leaves it at 48% of the shorter side.
 
+Radius precedence and the outputs intentionally left unmasked are documented in [Rounded non-icon artwork](./app-branding.md#rounded-non-icon-artwork). Normal and `--dry-run` summaries report effective padding and radius.
 **Optional asset types**
 
 | Flag | Purpose |
@@ -227,7 +239,6 @@ Splash padding is a share of the canvas's **shorter** side, so one number keeps
 | `--notification-icon` | Also emit `ic_stat_notify.png × 5`. |
 | `--splash-icon` | Also emit `splash_icon.png × 5`. |
 | `--nine-patch` | Declared but not implemented yet; prints a warning and writes nothing. |
-
 **Logo variants & overrides**
 
 Every piece has a `--<piece>-logo <path>` flag — with no exceptions since v7.13.0 — each overriding the matching `purgetss/brand/logo-<piece>.{svg,png}`:
@@ -235,7 +246,6 @@ Every piece has a `--<piece>-logo <path>` flag — with no exceptions since v7.1
 `--icon-logo`, `--dark-logo`, `--tinted-logo`, `--ios-splash-logo`, `--launch-logo`, `--marketplace-logo`, `--feature-graphic-logo`, `--adaptive-logo`, `--legacy-icon-logo`, `--appicon-logo`, `--android-splash-logo`, `--splash-icon-logo`, `--notification-icon-logo`.
 
 `--launch-logo` is the one that also **activates** its piece. Two more sources are not pieces: `--monochrome-logo <path>` (the silhouette shared by the adaptive monochrome layer and the notification icons, `logo-mono.{svg,png}`) and the positional `<logo>` argument (the main logo).
-
 **Output size**
 
 | Flag | Purpose |
@@ -274,11 +284,11 @@ Every piece has a `--<piece>-logo <path>` flag — with no exceptions since v7.1
 
 ### Config block (v7.13.0 per-piece structure)
 
-Defaults live under `brand:` in `purgetss/config.cjs`. Since v7.14.0, a standalone Classic run creates the canonical config when it is missing. The block has **one entry per piece**; each accepts the same four keys where they apply: `logo`, `padding` (never inherited), `background` (inherited from `brand.background`), `enabled`. Top-level: `background`, `confirmOverwrites`, `optimize`, `logo`, `monochromeLogo`.
+Defaults live under `brand:` in `purgetss/config.cjs`. Since v7.14.0, a standalone Classic run creates it when missing. Each piece accepts `logo`, `padding`, `cornerRadius`, `background`, and `enabled` where applicable; radius is valid only for the two legacy splashes, Feature Graphic, and LaunchLogo. Top-level settings include shared `artworkCornerRadius`, optional `splashCornerRadius`, background, persistence, optimization, and logo values.
 
 An unknown key aborts the run before a single file is written. A `brand:` block written for an older PurgeTSS is **rewritten on disk** on the next run, carrying over every customized value.
 
-Full annotated block and per-key reference: [app-branding.md → The `brand:` config section](./app-branding.md#the-brand-config-section) and [Older configs update themselves](./app-branding.md#older-configs-update-themselves). The recommended workflow is convention-first: drop files in `purgetss/brand/`, let auto-discovery pick them up, and use `config.cjs` only for a persistent override.
+Full annotated block and per-key reference: [app-branding.md → The `brand:` config section](./app-branding.md#the-brand-config-section). Use flags for one-run sources, geometry, selection, activation, background, or optimization; keep persistent preferences in `config.cjs`.
 
 ### Confirmation prompt
 
@@ -295,12 +305,12 @@ purgetss brand --adaptive-logo ./docs/app-icon.svg        # dedicated square And
 purgetss brand --splash-icon --splash-icon-logo ./docs/splash.svg  # custom Android 12+ splash artwork
 purgetss brand --launch-logo ./docs/wordmark.svg          # iOS launch screen logotype
 purgetss brand --feature-graphic-logo ./docs/feature.svg  # custom Google Play Feature Graphic
-purgetss brand --feature-graphic-padding 8                # tighter Feature Graphic padding
+purgetss brand --artwork-corner-radius 22                 # round supported non-icon artwork
+purgetss brand --splash-corner-radius 18                  # override both legacy splash sets
+purgetss brand --appicon-padding 14                       # temporary appicon.png inset
 purgetss brand --notification-icon --splash-icon          # add notification + splash icons
-purgetss brand --no-tinted                                # skip iOS 18+ tinted variant
 purgetss brand --optimize                                 # quantize the generated PNGs
 purgetss brand --dry-run                                  # preview without writing
-purgetss brand --cleanup-legacy --dry-run                 # preview legacy cleanup
 ```
 
 ### Android output groups
@@ -327,7 +337,7 @@ purgetss images background/                           # re-process one subfolder
 | `--android` | Only emit Android density variants. Mutually exclusive with `--ios`. |
 | `--ios` | Only emit iPhone scale variants. Mutually exclusive with `--android`. |
 | `--format <ext>` | Convert all outputs to `webp`, `jpeg`, `png`, `avif`, `gif`, or `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 Android `mdpi` (= iPhone `@1x`) to `<n>` pixels wide. Larger scales derive as ×1.5, ×2, ×3, ×4 from that base; height stays proportional to the source's aspect ratio. Integer in `[1, 8192]`. |
 | `--opacity <n>` | (v7.10.0) Multiply alpha of every density by `n/100`. Integer in `[0, 100]`. With `--format jpeg`, alpha flattens on white. |
 | `--padding <n>` | (v7.10.0) Shrink the rendered image inside each density canvas by `n%` symmetric borders. Integer in `[0, 40]`. |
@@ -365,12 +375,16 @@ Defaults live under `images:` in `purgetss/config.cjs`:
 
 ```javascript
 images: {
-  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' | 'avif' | 'gif' | 'tiff'
-  confirmOverwrites: true  // prompt before overwriting files
+  autoSync: true,          // false = SVG pipeline computes dims but doesn't write to images.files
+  confirmOverwrites: true, // prompt before overwriting files
+  files: []                // per-file overrides: [{ filename, width, height? }]
 }
 ```
 
+Those five keys are the whole section. Since v7.17.0 any other key — including `width`, `opacity`, `padding` and `output`, which are CLI flags — aborts the run before writing anything, and so does a `files[]` entry with an unknown key or no `filename`. See [Unknown keys are an error](./multi-density-images.md#unknown-keys-are-an-error-v7170).
+
 Like `brand`, `images` writes in place and asks `Continue? [y/N/a]` before overwriting. Selecting `a` flips `confirmOverwrites: false` in `config.cjs`. Skipped automatically when `stdin` is not a TTY, when `-y`/`--yes` is passed, or when `PURGETSS_YES=1` is set.
 
 ### Examples
@@ -477,6 +491,15 @@ purgetss install-dependencies
 purgetss id
 ```
 
+### What it installs (v7.17.0)
+
+`npm i -D eslint @eslint/js` plus a flat `eslint.config.mjs` in the project root, `.editorconfig`, `.vscode/{extensions,settings}.json` when the `code` command exists, and `tailwindcss@3` for IntelliSense. `create --dependencies` runs the same ESLint and Tailwind steps. `eslint-config-axway` and `eslint-plugin-alloy` are no longer installed.
+
+The shipped config declares the Titanium and Alloy globals itself (`Ti`, `Titanium`, `Alloy`, `Backbone`, `$`, `$model`, `_`, `L`, `Widget`, `OS_*`, `ENV_*`, `DIST_*`, `console`, `alert`, the timer functions, and `task` for `alloy.jmk`). It lints `app/**/*.js` and ignores `Resources/`, `build/`, `node_modules/`, `purgetss/`, plus the six libraries PurgeTSS copies into `app/lib/`, listed by name so the developer's own files there keep being linted. `no-unused-vars` is a **warning**: Alloy wires handlers from the XML view, so a controller function with no caller in the JS may still be in use.
+
+> **Warning**
+> Before v7.17.0 this command shipped an `.eslintrc.js` extending `eslint-config-axway/env-alloy` and installed `eslint-plugin-alloy`. That setup cannot run under ESLint 9 — it stopped reading `.eslintrc.*`, axway removed `env-alloy` in `eslint-config-axway@10.0.0`, and the unmaintained plugin throws `This method cannot be used with flat config`. Projects scaffolded between December 2025 and v7.17.0 have a lint that never ran; re-run `purgetss install-dependencies` to replace it.
+
 > **Caution**
 > This command overwrites any existing `extensions.json` and `settings.json` files. Back them up if you want to keep your current versions.
 
@@ -521,13 +544,14 @@ purgetss bf [-m] [-f]
 
 | Flag | Purpose |
 | --- | --- |
-| `-m, --module` | Also generates `app/lib/purgetss.fonts.js` (Alloy) or `Resources/lib/purgetss.fonts.js` (Classic), exposing `exports.icons` and `exports.families`. |
+| `-m, --module` | Also generates `app/lib/purgetss.fonts.js` (Alloy) or `Resources/lib/purgetss.fonts.js` (Classic). `exports.families` contains every processed TTF/OTF PostScript name; icon CSS additionally populates `exports.icons`. |
 | `-f, --font-class-from-filename` | Uses the font filename as the class name and icon prefix instead of the font family. Replaces the old `-p` flag. |
 
 ### What it does
 
 1. Copies font files to `app/assets/fonts/` (Alloy) or `Resources/fonts/` (Classic), renamed to their PostScript names.
 2. In Alloy only, creates `purgetss/styles/fonts.tss` with the TSS class definitions.
+3. With `--module`, creates the CommonJS module even for text-only font collections. Classic loads it with `require('lib/purgetss.fonts')`; see the [Classic module path table](./classic-projects.md#loading-generated-modules-in-classic).
 
 > **Tip**
 > This is a quick reference. See [Custom Fonts](./custom-fonts.md) for the complete guide — folder organization, class renaming, adding icon libraries, the `--module` output structure, and `--font-class-from-filename` workflow.
@@ -539,7 +563,7 @@ purgetss bf [-m] [-f]
 
 The `shades` command generates shades and tints for a given color and writes the palette to `config.cjs`.
 
-Saving works in Alloy and Classic. In Classic, `config.cjs` is only a development-time color source for commands such as `color-module`; it does not install the PurgeTSS utility lifecycle. `--log`, `--json`, and `--tailwind` write nothing and work outside a project.
+Saving works in Alloy and Classic. In Classic, `config.cjs` is only a development-time color source for commands such as `color-module`; it does not install the PurgeTSS utility lifecycle or create empty brand, font, or image source folders. If `Resources/lib/purgetss.colors.js` already exists, saving refreshes it. `--log`, `--json`, and `--tailwind` write nothing and work outside a project.
 
 ```bash
 purgetss shades [hexcode] [name]
@@ -641,7 +665,9 @@ purgetss s '#65e92c' -j
 
 ## `color-module` Command
 
-This command creates `purgetss.colors.js` with all colors defined in `config.cjs`: `app/lib/` in Alloy or `Resources/lib/` in Classic. A missing config is created as the color source, but Classic receives no Alloy hook or TSS.
+This command creates `purgetss.colors.js` with all colors defined in `config.cjs`: `app/lib/` in Alloy or `Resources/lib/` in Classic. A missing config is created as the color source, but Classic receives no empty `purgetss/brand/`, `purgetss/fonts/`, or `purgetss/images/` folders, Alloy hook, or TSS.
+
+Classic loads the result with `require('lib/purgetss.colors')`; see [Classic module paths](./classic-projects.md#loading-generated-modules-in-classic).
 
 ```bash
 purgetss color-module
@@ -706,12 +732,17 @@ The command installs a task in `alloy.jmk`:
 
 ```javascript
 task('pre:compile', (event, logger) => {
-  require('child_process').execSync('purgetss', logger.warn('::PurgeTSS:: Auto-Purging ' + event.dir.project));
-});
+  logger.warn(`::PurgeTSS:: Auto-Purging ${event.dir.project}`)
+  try {
+    require('child_process').execSync('purgetss', { stdio: 'inherit' })
+  } catch (error) {
+    logger.error('::PurgeTSS:: Auto-Purge failed. Run `purgetss` from the project root to see the cause.')
+    throw error
+  }
+})
 ```
 
-> **Info**
-> This feature works with standard Alloy projects compiled using `ti build`. It has not been tested with project types built using Webpack or Vue.
+The default synchronous hook inherits CLI output so validation details appear before Alloy's generic failure. Async mode forwards `stdout` and `stderr` and prints the same final hint. `init` refreshes old active or disabled hooks without changing their state; invoking `watch` normally enables a disabled hook.
 
 To deactivate it, use `--off`.
 
@@ -733,7 +764,9 @@ purgetss w -d
 
 ## `module` Command
 
-The `module` command installs the self-contained `purgetss.ui.js` in `app/lib/` (Alloy) or `Resources/lib/` (Classic). A Classic app does not need PurgeTSS during compilation or at runtime.
+The `module` command installs the self-contained `purgetss.ui.js` in `app/lib/` (Alloy) or `Resources/lib/` (Classic). Classic executes that generated file but needs no PurgeTSS CLI/package at build time or as an app dependency.
+
+Classic loads it with `require('lib/purgetss.ui')`; see [Classic module paths](./classic-projects.md#loading-generated-modules-in-classic).
 
 ```bash
 purgetss module
@@ -742,11 +775,7 @@ purgetss module
 purgetss m
 ```
 
-The PurgeTSS module includes:
-
-- Animation: methods for playing or applying basic animations and transformations to Titanium views.
-
-See [Animation System](./animation-system.md) for details.
+The module exports `AnimationProperties`, `createAnimation(args)`, `Appearance`, `deviceInfo()`, and `saveComponent()`. Its animation object exposes 15 state, drag, collision, position, feedback, and layout methods. See [Animation System](./animation-system.md) for Alloy or [`purgetss.ui` in Classic](./purgetss-ui-classic.md) for native JavaScript.
 
 ## `update` Command